Webhooks (Real-Time Events)

Webhooks are useful for receiving events from the phone system, in real-time, in the form of a POSTed data to your own API. Please note, some webhooks are JSON and some are URLENCODED.

---

SMS / MMS Messages (JSON)

Setup: Call Routing > Inbound > Edit Phone Number > API/Webhooks tab

Inbound Message:

{
"eventType": "inboundMessage",
"toNumber": "{TO_NUMBER}",
"fromNumber": "{FROM_NUMBER}",
"containerID": "{CONTAINER_ID}",
"tenantID": "{TENANT_ID}",
"conversationID": "{CONVO_ID}",
"messageText": "{ESCAPED_MESSAGE_TEXT}"
}

Outbound Message:

{
"eventType": "outboundMessage",
"toNumber": "{TO_NUMBER}",
"fromNumber": "{FROM_NUMBER}",
"containerID": "{CONTAINER_ID}",
"tenantID": "{TENANT_ID}",
"conversationID": "{CONVO_ID}",
"messageText": "{ESCAPED_MESSAGE_TEXT}"
}

Explanation: Whenever an inbound text message is received from an outside number (like someone's cell phone) you will receive an inboundMessage event. The "FROM" number will be the outsider, and the "TO" number will be the number they texted that belongs to the PetDesk Phones customer.

Conversely, whenever an outbound message is sent from a PetDesk Phones user (via our web portal, mobile/desktop apps, or SIP SIMPLE messaging) then you will receive an outboundMessage event, where the "FROM" number is the PetDesk Phones customer's number, and the "TO" number is the outsider.

---

Inbound Calls (URLENCODED body)

Setup: Call Routing > Inbound > Edit Phone Number > API/Webhooks tab

Inbound Call:

eventType=InboundCall&eventTarget=phoneNumber&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&didNumber={PHONE_NUMBER}&didDescription={PHONE_NUMBER_DESCRIPTION}&didGroup={GROUP_NAME}&cidPrefix={CALLERID_PREFIX}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}&callerIdName={FROM_NAME}

Hangup Call:

eventType=HangupCall&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Explanation: When a call initially comes into the phone system, even before it does anything, we will fire off an InboundCall webhook event. No matter what happens to the call, the HangupCall event will be fired whenever the call ends. If the call had been answered by a real live person (extension), then extNumber and extName will be filled with that information.

Outbound calls are not configured in this way, and must utilize the Extensions settings in the next section.

---

Extensions + Outbound Calls (URLENCODED body)

Setup: Extensions > Manage > Edit Extension > API/Webhooks tab

Extension Ringing:

eventType=ringAttempt&eventTarget=extension&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}

Extension Answered:

eventType=ExtensionAnswered&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}&callerIdName={FROM_NAME}&extensionNumber={EXTENSION_NUMBER}&extensionName={EXTENSION_NAME}

Extension Hung Up:

eventType=inboundCallCompleted&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Voicemail Left by Caller:

eventType=voicemailHangup&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Outbound Call Placed Syntax: 

eventType=outboundCall&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&numberDialed={NUMBER_DIALED}

---

Ring Groups (URLENCODED body)

Setup: Call Control > Ring Groups > Edit Ring Group > API/Webhooks tab

Caller Enters Ring Group:

eventType=ringAttempt&eventTarget=ringGroup&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&rgNumber={RING_GROUP_EXTEN}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}

---

Queues (URLENCODED body)

Setup: Call Control > Queues > Edit Queue > API/Webhooks tab

Caller Enters Queue:

eventType=queueEntered&eventTarget=queue&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&queueNumber={QUEUE_EXTEN}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}