What are Webhooks
Webhooks are one way that apps can send automated messages or information to other apps. It's how Spoke tells Zapier about a new voicemail in ClearlyCloud, or how Spoke notifies Zoho PhoneBridge about an incoming call. Spoke comes with a Webhooks app pre-installed that allows you to connect ClearlyCloud to any third party app or an in-house solution that supports Webhooks.
Webhook Apps
The Webhook app allows you to trigger messages on phone call events like an answered incoming call or media events like a new voicemail. These messages are sent to a unique URL that you provide when adding a new webhook in Spoke.
Webhook types
Currently, the Webhooks app supports 2 types of webhooks: call webhooks and media webhooks.
Call Webhooks:
Call Webhooks are used when you want to send a message when anything related to phone calls occurs in ClearlyCloud, for example a new incoming call was missed or an outgoing call ended. You can choose which events will trigger a new message using the different options for call types and call statuses. You can select just a call type, just a call status or a combination of both.
Example: To trigger the webhook when an agent misses a call, select call type “Incoming Call” and call status “Missed”
- Incoming Call
- Outgoing Call
Call statuses
- Ringing
- Answered
- Ended
- Missed
- Busy
- Invalid
- Blocked
- Not available
- No answer
- Rejected
Payload
Call Webhooks send a payload with the phone call details. Depending on the call status some additional fields might be added to the payload but overall the structure is similar. Below is an example payload for a call webhook, with call type “incoming call” and status “ringing”.
"id": "6d739560-1741-11ed-861d-0242ac120002",
"thread_id": "54144414-9e16-49de-8830-b2475a8dc7ea",
"to": "5010",
"from": "+19203833100",
"to_name": "Dade Murphy",
"from_name": "Clearly IP",
"type": "incoming_call",
"subtype": "ringing",
"timestamp": "2023-11-14T21:45:22.000000Z"
Media Webhooks:
Media Webhooks are used when you want to send a message when there’s a new voicemail or call recording. You can choose which events will trigger a new message using the different options for media types.
- Voicemail
- Call Recordings *
Example: To trigger the webhook when a new call recording is available, select media type “Call Recording”
* NOTE: call recordings are only triggered when the user making the call has call recording enabled in ClearlyCloud.
Payload
Media Webhooks send a payload with the phone call details and a temporary link to download the audio file in mp3 format of the call recording or voice mail. The temporary download link expires in 24 hours.
"id": "6d739560-1741-11ed-861d-0242ac120002",
"thread_id": "54144414-9e16-49de-8830-b2475a8dc7ea",
"to": "5010",
"from": "+19203833100",
"to_name": "Dade Murphy",
"from_name": "Clearly IP",
"type": "call_recording",
"filename": "recording_2024-07-19 00:00:00 -0500_from:15053430650_to:5012-508_116612489.mp3",
"content_type": "audio/mpeg",
"attachments": "https://spoke.clearlyip.com/api/media/download/ad1c5ba3-9f9b-454d-b4b1-cfb592bb8fd9?expires=1721507312&signature=541444149e1649de8830b2475"
Setting up the Webhooks integration
🛑 Verify Requirement: Have you enabled ClearlyIP Spoke? (If not, start here.)
Setup
- Click the “Connect” button on the Webhooks card.
- Select the ClearlyCloud location to connect to Webhooks and click on “Authorize”.
- You’ll be redirected to the Spoke main page, and you should be able to see a “ClearlyCloud & Webhooks” card under the active integrations section. Click on “Manage Webhooks” to add or delete webhooks.
- Click on “Add New Call Webhook” or “Add new Media Webhook”
- Choose the call type and status that will trigger the webhook and type the URL where Spoke should send the messages. You can use https://webhook.site/ to create a unique test URL for your webhooks.
Uploading ....