V1 (version 1)
Purpose
The purpose of this webhook is to enable a M8Com customer to use an external answer service provider to handle certain incoming calls. By implementing an integration with the answer service provider and the M8Com application, through this webhook, the answer service provider can have access to the very latest status information regarding the customer and its users. Access to this data will help the answer service provider with how to handle each incoming call.
Some examples of real-time data that is provided through a webhook integration:
- Users
- Name
- Numbers
- Line state
- Activity status
- Structural entities (location, title, department, …)
- …
- Company
- Name
- Org number
When an integration has been setup, M8Com calls the webhook endpoint in real-time whenever something changes on the customer.
Setup in M8Com
A user with Superadmin access to a customer will be able to setup answer service integrations in the M8Com app. The setup is done in Organisation Settings / Answer Service. As part of the setup, the Data Model version must be selected, preferably matching the latest version supported by the answer service provider (see the data model version history below).
The following data is needed to setup a new integration and should be provided by the answer service provider.
- Endpoint, the endpoint M8Com must send data to when users/company info changes. https protocol is required and needs to be included in the endpoint URL when setting up the integration.
- Secret, a unique key or identifier that can be used by the answer service provider to identify the request (for example which customer the request applies to)
- 123ExampleCustomer321
After the integration is created in the M8Com app, it will be assigned a unique ID (”Integration token”) that must be used by the answer service provider when making requests to the M8Com API endpoint. The token can be copied from the recently set up integration in the M8Com app.
The token must be handed over to the answer service provider by the one responsible for setting up the integration on the customer account in the M8Com app.
Webhook Requests
When a new integration is connected a complete sync of company data and all users will be performed. After setup is finished, changes to users or company data will trigger a request to be made to the endpoint in the connected integration.
{
"uri": ENDPOINT,
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": `Bearer ${SECRET}`
},
"body": {
, // See the Data Model version spec(s) for the details
"completeSync": false // True when a sync is triggered
}
}
A complete Data Model will always be provided regardless of what parts of the Data Model that changed. Note that this may result in a requests being made where nothing in the compiled data actually changed.
In the case that much data has been changed at the same time the request will be chunked up before being sent out.
“completeSync” will be included in the first request made (if it’s chunked) when a sync is triggered any previously stored data can be dropped at this point.
Answer service unavailable
In the case that endpoint does not respond with 200 when requests are made. M8Com will attempt to resend the changes using exponential back-off before disabling the integration. A disabled integration can be restarted from M8Com if the secret is known by an admin or by the answer service provider requesting a sync of the integration, (see below).
M8Com API endpoint
The answer service provider can use the following endpoint to trigger a complete data sync.
- https://app.m8com.io/services/answer-service-api/vX/sync-integration
- Note 1: https://app.m8com.io prefix can be replaced with any whitelabel path (e.g. app.m8com.io for the M8Com Realm), but the app.m8com.io prefix works for all Realms.
- Note 2: “vX” must be the version number, e.g. “v1” for version 1.
Requests should be made in the following format. On success you’ll get back 200 Sync started and the data will be sent to the registered endpoint.
{
"uri": "/services/answer-service-api/v1/sync-integration",
"method": "POST",
"headers": {
"Authorization": `Bearer ${SECRET}:${INTEGRATIONID}`
},
}