Integrating your dialer with MosaicVoice
Overview
To ensure smooth integration and real-time guidance for your team, our application requires webhook notifications from your dialer to track changes in call states. These notifications allow us to monitor ongoing calls and provide timely insights. The key call states we track include call start, call end, and disposition. Additionally, we use agent identifiers, such as user_id or user_name, to match calls to the correct agent in our system.
Please note, while we have provided recommended field names, we understand that each dialer may use different field names, and we can work with you to accommodate variations.
Required Webhook Events
Your dialer should send webhook notifications for the following call states:
- Call Start – When a call is initiated.
- Call End – When a call is completed.
- Call Disposition – The final outcome of the call (e.g., completed, voicemail, missed).
Flexible Field Naming
While we suggest the following field names for simplicity, we recognize that your dialer may name these fields differently. We are able to accommodate different naming conventions as long as the necessary data is present in the payload.
Example fields:
● call_id: A unique identifier for the call.
● state: The current call state (e.g., start, end, disposition).
● timestamp: The event timestamp in ISO 8601 format.
● user_id or user_name: Identifier for the agent handling the call.
● disposition: The final call outcome (for call end/disposition events).
Example payload for a call start event:
{
"call_id": "1234567890",
"state": "start",
"timestamp": "2024-10-09T12:00:00Z",
"user_id": "agent_123"
}
If your dialer uses different field names, please share them with us so we can configure our system accordingly.
Webhook Configuration Requirements
- Webhook URL:
Configure your dialer to send HTTP POST requests to the following endpoint:
https://app.mosaicvoice.ai/dialer-id/custom-endpoint-id/webhooks/call
- Timely Notifications:
We request that call state updates be sent promptly to ensure our application can provide real-time guidance. Delays may impact the quality of insights.
Authentication
For added security, we recommend authenticating webhook requests using one of the following methods:
API Key (Preferred):
We can generate an API key for your integration, which can be included either:
- In the response headers as x-api-key, or
- As a query parameter, e.g., ?X-api-key=your-key.
Example:
POST https://app.mosaicvoice.ai/dialer-id/custom-endpoint-id/webhooks/call?X-api-key=your-key
However, we understand that some dialers may not support adding custom authentication methods. Therefore, authentication is recommended but not required.
Testing and Validation
We recommend performing a series of test calls after setup to confirm that the webhook is functioning correctly, and that call state updates are reaching our system in real-time.