Integrations - Webhooks¶

Webhooks are triggered by Call Event, such as call ringing, call answered, call hangup etc. When that event occurs, VoIPstudio platform makes an HTTPS (POST) request to the URL configured for the Webhook - a third party web server (API). See more more on Wikipedia

1. Click on Integrations.
2. Scroll down to Webshooks and Enable.
3. Select Add Webhook to create a new one.
4. Enter any name for the new Webhook to indentify.
5. Select events to listen for. Note Call State change type include all events.
6. Enter the URL used by your application.
7. To Edit any Webhooks simply click on the name.
8. If no longer needed simply click disable Webhooks.

NOTE: Only HTTPS Protocol is supported.

NOTE: For URL to be saved it need to be valid and reply to https requests.

Available events¶

With VoIPtudio WebHooks we monitor following call status events categories:

• Call State Change - triggered for any call state change: INITIAL, RINING, CONNECTED, ON_HOLD, HANGUP.
• Call Ringing
• Call Connected
• Call Ended
• Call Missed
• Call DTMF received

Note: webhook events show call status and they are matching SIP signalling messages as detailed bellow:

• INITIAL: SIP INVITE send to the corresponding endpoint (Phone).
• RINGING: endpoint reply from SIP INVITE. It is indicating that the endpoint is active and it is already ringing.
• CONNECTED: SIP 200 message indicating that user answered the call.
• ON_HOLD: The call has ben paused. This corresponds to SIP INVITE with body: a=sendonly
• HANGUP: indicating that call has ended. This corresponds to SIP BYE Message.

Apart from call status events, the following additional events are available:

• SMS received
• Queue wrap up - emitted when post call Wrap Up panel opens, closes or times out.

Event attributes¶

Events are delivered as HTTPs POST requests with JSON body - for example:

{
  "id":"uk003.608920d55f7ac3.77053295",
  "event_time":"2021-04-28 08:46:13",
  "event_name":"call.hangup",
  "call_id":139543232,
  "state":"HANGUP",
  "connected_at":"2021-04-28 08:46:02",
  "start_time":"2021-04-28 08:45:55",
  "context":"LOCAL_USER",
  "destination":"in",
  "duration":11,
  "t_cause":"Normal Clearing",
  "src":"447854740947",
  "src_id":"0",
  "src_name":"\"442035141598\" <2035141598>",
  "src_hash":"fe5935cefbc82fc4e924bdaa21342a49c18c5dd9",
  "dst":"441183211001",
  "dst_id":"10002",
  "dst_name":"John Smith",
  "terminated_by": "caller"
}

Additionally for "DTMF received" event call.dtmf two extra attributes are present:

  "dtmf_tag":"*",
  "dtmf_target":"U:123456"

Call status event attributes are as follows:

• id (string) - unique ID of an Event
• event_time (string) - time of an Event in Y-m-d H:i:s format UTC timezone
• event_name (string) - name of an Event, one of:
  • call.initial - Call in initial state
  • call.ringing - Call is ringing
  • call.missed - Missed (unanswered) call
  • call.connected - Call is connected
  • call.hangup - Call is terminated
  • call.hold - Call is put onhold
  • call.unhold - Call is unhold
  • call.dtmf - In call DTMF is received
• call_id (integer) - this is numeric ID of the call. It can be later used to access resources via REST API. The relation to REST API resources is:
  • call.id - example REST API request:
  • cdr.live_id - example REST API request: GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
  • monitor.live_id - example REST API request: GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
• state (string) - state of the Call, one of:
  • INITIAL - Initial call state
  • ACCEPTED - Click 2 call has been accepted
  • RINGING - Destination is rining
  • CONNECTED - Call is connected
  • ON_HOLD - Call is on hold
  • HANGUP - Call is terminated
• connected_at (string) - time when call was connected in Y-m-d H:i:s format UTC timezone. Default null
• start_time (string) - time when call started in Y-m-d H:i:s format UTC timezone.
• context (string) - context of the call within PBX system
• destination (string) - in for inbound call, out for outbound call
• duration (integer) - duration of the call is seconds
• t_cause (string) - Termination Cause
• src (string) - Number of the call source
• src_id (integer) - Numeric ID of call source
• src_name (string) - Name of the call source
• src_hash (string) - Unique ID for single call
• dst (string) - Number of the call destination
• dst_id (integer) - Numeric ID of call destination
• dst_name (string) - Name of the call destination
• terminated_by (string) - Designates party which terminated the call caller or called

SMS Received event attributes are as follows:

• id (string) - unique ID of an Event
• event_time (string) - time of an Event in Y-m-d H:i:s format UTC timezone
• event_name (string) - name of an Event sms.received
• customer_id (integer) - Numeric ID of Customer Account which received SMS message
• user_id (integer) - Numeric ID of User Account which received SMS message (optional, default: null)
• from_no (string) - originating phone number
• to_no (string) - phone number which received SMS message
• text (string) - body of received message

Queue Wrap up event attributes are as follows:

• event_name (string) - queue.wrapup
• state (string) - state of the Wrap up panel:
  • START - panel has been opoened
  • END - panel has been closed by an Agent
  • TIMEOUT - panel was clsosed automatically due to timeout

all attritutes are the same as Call Event described below, with the exception of:

Related REST API endpoints¶

After receiving Webhook event as in example above (call_id = 139543232), one can retrieve and update Call resource via REST API:

GET /v1.1/calls/139543232

and to Transfer the call to extension 2002:

PATCH /v1.1/calls/139543232
{
  "dst": "2002"
}

Note: /calls REST API resource represents active ongoing call. Once call is terminated and Event call.hangup received it is no longer available at /calls endpoint. Instead it can be accessed at /cdrs (Call Details Report) and /monitors (Call Recordings) endpoints using filter on live_id attribute with value of call_id from Webhook event, for example:

GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

or

GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

Context attribute - Queue¶

As we have seen, context attribute may have several values depending on the object that we generate them. If we like to monitor the events that occur in a user, we will need to look for attribute with context value LOCAL_USER but if we want to monitor the events that occur in a queue, we will filter by theQUEUE context.

Note: to start receiving Queue events we will need at least one Webhook on type Call Status Change. As this is generating events for every objet.

These event context allow us to identify when a call has not been answered by any agent. Either because the maximum wait time has been reached or you just user got tired of waiting and ended the call. So to identify an unanswered call within a queue instead of inspecting the Context = User we will look for an event with context:Queue and event_name:call.missed.

Troubleshooting Webhooks¶

Call detailed Reports from VoIPstudio dashboard allow customers to monitor all SIP packets workflow in a graphical view for every single call. It also display the Webhooks notifications send to your listening URL, including their content. This might be very useful to troubleshoot your Webhooks notification deployment.

You only need to browse Call Detailed Report and click on corresponding calls and check for the submitted events and their content. This should match the notification you received on server. Please follow steps bellow:

1. From Admin dashboard panel open History section.
2. Click CDR, this will open list with recent calls processed under VoIPstudio platform.
3. Identify and click the call you would like to inspect to open detailed info of the corresponding call.
4. Under call flow identify your API server column.
5. You must see one POST request send to the server for each event you ave Webhook event set. Click on it to expand.
6. Details of the Webhook post reply are shown here.