Plan requirement
| Subscription | x-bees Standard or higher, UC-Business or higher (Collaboration 7) |
| Also required | Cloud Analytics |
| Access | WMS administrator |
| WMS version | 6.03 or higher |
Wildix can post call, presence and transcription events to your own system. What it sends, what your endpoint must do, and how to see what went out.
What a webhook is for here
A webhook makes things happen without anybody looking at a screen: writing calls into a system of record, starting a workflow, updating a dashboard. If instead you want a page to open in front of an agent when the phone rings, that is a popup URL, and it is a great deal less work.
Check Cloud Analytics first
Webhooks depend on Cloud Analytics being enabled under PBX > Features. On a cloud system it is on by default, so this is usually fine, but it is the first thing to look at if events never arrive.
Setting it up
In WMS, go to PBX > Integrations > Cloud integrations, click Webhook integration, then Add new integration. Choose how events are sent: straight to a URL of yours, or onto an AWS SQS queue if you would rather have a queue absorbing them.
Give it the address, and pick which events you want. A Secret is generated for you and cannot be changed.
One may already be there
Turning on Integrations Hub adds a webhook integration by itself. So a list that already has an entry is not necessarily somebody else's work, and deleting it to start clean can take something with it that the hub relies on. Look at what it points at before you touch it.
What you can subscribe to
- Call events, with the call detail including addresses and ports, location where it is known, and recording start, pause, resume and stop.
- Presence events, both the user's own status and the telephony one: registered, ringing, talking, or ringing while already talking.
- Analytics events, which is the interesting one. When a transcription or a summary finishes, the full text can be sent to you.
- Conference, chat, SMS and WhatsApp events.
Within each type you choose individual events rather than taking everything, which is worth doing: a busy system produces a great many.
Presence events need an extra step on Collaboration. On x-bees they are sent by default. On a Collaboration subscription, a configuration change on the PBX is needed first, so ask us to switch it on rather than assuming the subscription is broken.
What your endpoint has to do
- Be reachable from the internet, over HTTPS with a valid certificate
- Accept POST requests with a JSON body
- Answer with a 2xx status, and quickly: the reply times out after five seconds
- Tolerate receiving the same event more than once. A failure is retried up to three times, so anything that writes a record needs to cope with duplicates
- Check the x-signature header before trusting the contents. The endpoint is public, and this is what proves the event came from your phone system
That five-second timeout is worth designing around. Accept the event, put it on a queue, answer immediately, and do the work afterwards.
Seeing what went out
Under Cloud integrations > Webhook, the Activity section has View Traces. Open a webhook ID there and you can read the event as it was sent. It settles the usual argument about whether the phone system sent something or the receiving end dropped it.
Getting the number to match
Numbers arrive in international format. If your database stores them locally, normalise before matching or nothing will ever be found. The integration then appears not to work, while it is matching correctly against a format your database does not use.
If you are not sure whether you want a webhook or a popup URL, describe what should happen and we will tell you which one fits.
Comments
0 comments
Article is closed for comments.