Event Reference
This is a reference of RealTime events that you may receive on your event streams. Event names are listed in topic format. These RealTime events are officially supported and are guaranteed to remain stable. You may see other events, but beware: The use of any events that are not in this list is not supported. Unsupported events may change without notice, or may disappear completely.
Think of an event as something that happened: We received a call, somebody answered a call, a number on your account received a text message. Events are not directly coupled to event streams. Streams only dictate why or how you will receive events, depending on the nature of the stream: Your user, entire account, etc.
Voice events represent various call activities that occur on your account. Each one of these will have a property called trackingId. You can use this to track call progress from start to finish to monitor calls in real time.
Some events will also have a property called uniqueId. This is also known as the report id, or call id value in the REST API and possibly other places. It represents the individual call.
| Event Name | Description |
|---|---|
| voice.incoming.start | An incoming call has reached your account. We’ve begun to process it. |
| voice.incoming.answer | Someone or some thing has answered an incoming call. This doesn’t mean a human answered. It could be a voicemail system, some other PBX, so on. |
| voice.incoming.end | An incoming call has ended. |
| voice.outgoing.start | A user has has placed an outgoing call using a SIP device (phone or app). If a call was made using the originate REST API, that will also generate this event. However, voice.originate.start happens first in that case. |
| voice.outgoing.answer | Someone or some thing has answered an outgoing call. This doesn’t mean a human answered. It could be a voicemail system, some other PBX, so on. |
| voice.outgoing.end | An outgoing call has ended. |
| voice.internal.start | A call between two internal users has started on your account. |
| voice.internal.answer | Someone has answered the internal call. |
| voice.internal.end | An internal call has ended. |
| voice.originate.start | We just received a REST API request to originate a call, and we’re calling the originating caller. |
| voice.originate.answer | The originating caller has answered (it could be voicemail, beware). Next, look for voice.outgoing.start which represents the call to the callee. Keep following the outgoing events with the trackingId. |
| voice.originate.end | The voice origination has ended. Use this to get an data on the originating caller leg of the call. If we started calling the callee, you’ll also get a voice.outgoing.end event. |
| voice.callconfirm.start | The leg of the call has call confirmation enabled and we’re playing a message to confirm the call. Even though something answered, a human now has to press a key on their phone to accept the call before we connect the parties together. |
| voice.callconfirm.acceptcall | The call leg was confirmed by a pressing a key to accept it. We will now connect the two parties together and disconnect any other potential parties that have yet to confirm. |
| voice.callconfirm.rejectcall | The call leg did not confirm. We did not connect this party. |
| voice.incoming.agentpin-prompt | The incoming call has agent PIN entry mode on. The receiving party must enter their PIN before we connect them. We have just played a message prompting them to do so. You will see this every time we play the message. |
| voice.incoming.agentpin-valid | The receiving party has entered a valid PIN. We have connected the receiving party together to the calling party. This incoming call is now associated with the user matching the PIN entered. |
| voice.incoming.agentpin-timeout | The receiving party did not enter a PIN in time. We have disconnected the incoming call. |
The following events occur when messages are sent or received on your account. For texts, messages may or not may not be associated with a user id, but they’ll always be associated with an active number and line.
You’ll also find a uniqueId data property in some events, which represents the individual message. Like the uniqueId in voice calls, it’s also known as the report id, or call id value in the REST API and possibly other places.
| Event Name | Description |
|---|---|
| messaging.incoming.sms | An incoming SMS message was received. |
| messaging.outgoing.sms | An outgoing SMS message was sent. |
| messaging.incoming.mms | An incoming MMS message was received. You’ll get the text part in this event. If you need to download the media, use the message component REST API endpoint. |
| messaging.outgoing.mms | An outgoing MMS message was sent. |
| messaging.update.opt-out | Someone has just opted-out of texts on your account by sending the opt-out command to one of your numbers. Their number is now on your account-wide opt-out list. |