Send Voice Interactive
Send interactive voice messsages.
https://frogapi.wigal.com.gh/api/v3/voice/send/dynamic
Request Object
| Field | Type | Description |
|---|---|---|
| callerid | string | The caller ID used for the voice call |
| servicetype | string | The type of service. Default is "CALL" |
| destinations | array | Array of destination objects containing destination phone number and message ID |
| destinations[].destination | string | Recipient Phone Number |
| destinations[].msgid | string | Your message ID |
Response Object
| Field | Type | Description |
|---|---|---|
| status | string | The status of the request |
| message | string | The message response |
Responses
| Field | Type | Description |
|---|---|---|
| status | string | Returns "ACCEPTD" when message is accepted for processing |
| message | string | Returns "Message Accepted For Processing" on successful request |
| Field | Type | Description |
|---|---|---|
| status | string | Error status code ("INVALID_REQUEST") |
| message | string | Detailed error message explaining the issue |
| Field | Type | Description |
|---|---|---|
| status | string | Error status code ("UNAUTHORIZED") |
| message | string | Message Response |
| Field | Type | Description |
|---|---|---|
| status | string | Error status code ("FORBIDDEN") |
| message | string | Message Response |
| Field | Type | Description |
|---|---|---|
| status | string | Error status code |
| message | string | Detailed error message explaining the issue |
| Field | Type | Description |
|---|---|---|
| status | string | Returns "ERROR" for server errors |
| message | string | Generic error message "Internal server error" |
Voice Callback URL
Your Voice Callback URL allows FROG to send real-time call events to your application and receive your responses to control the interactive voice call flow.
How It Works
- Provide Your Callback URL To Frog By Configuring It In Your Account Settings.
- When call events occur (e.g., DIALED, RINGING, ANSWERED, ENDED), FROG will send an HTTP POST request to your callback URL with relevant call data.
- Your endpoint should process the callback and respond with an action to control the call flow (e.g., READ, PLAY, COLLECT, RECORD).
Callback to you
FROG will send an HTTP POST request to your callback URL endpoint with the following payload structure:
Request Payload
{
"channelid": "CH123456789",
"activitytime": "2024-04-23T14:59:14.143+00:00",
"additionaldetails": "Call connected successfully",
"event": "ANSWERED",
"batchid": "BATCH001",
"callfrom": "233276128036",
"callto": "233276128037",
"clientid": "MSG123456789",
"callstarttime": "2024-04-23T14:58:00.000+00:00",
"callendtime": "2024-04-23T14:59:30.000+00:00",
"callduration": 90,
"direction": "Outbound",
"keypressed": "1"
}
| Field | Type | Description |
|---|---|---|
| channelid | string | The unique ID for the call generated by Wigal |
| activitytime | string | Timestamp of the event |
| additionaldetails | string | Any additional details for the event |
| event | string | The event type (see Events list below) |
| batchid | string | Batch ID from Wigal |
| callfrom | string | The caller ID |
| callto | string | The destination number |
| clientid | string | The unique ID the customer input when initiating the call (message ID) |
| callstarttime | string | Timestamp when the call started |
| callendtime | string | Timestamp when the call ended |
| callduration | integer | Duration of the call in seconds |
| direction | string | Call direction: "Inbound" or "Outbound" |
| keypressed | string | Any key pressed during the call |
Events
The following events can be sent to your callback URL:
- DIALED - Call has been dialed
- RINGING - Call is ringing
- ANSWERED - Call has been answered
- PROGRESS - Call is in progress
- ENDING - Call is ending
- ENDED - Call has ended
Actions
The following actions can be sent in your response to control the call flow:
Note: Actions can also trigger events depending on the action type. For example, when you send a PLAY action, you may receive events related to playback status. Similarly, COLLECT actions may generate events when digits are pressed, and RECORD actions may trigger events related to recording status.
- READ - Read text to the caller
- PLAY - Play audio to the caller
- COLLECT - Collect input from the caller (DTMF)
- RECORD - Record audio from the caller
- DISCONNECT - Disconnect the call
- STOPRECORD - Stop recording audio
- STOPPLAY - Stop playing audio
- CONTINUE - Continue with the next step in the flow
Audio Format Requirements: For PLAY and RECORD actions, the
actiondata field must contain an accessible audio URL. The audio file must be in WAV format with the following specifications:
- Format: WAV (a-law)
- Channels: Mono
- Sample rate: 8KHz
- Bit rate: 64kbps
Response from your Callback
Your endpoint should respond with the following payload structure to control the call flow:
Response Payload
{
"channelid": "CH123456789",
"action": "PLAY",
"actiondata": "https://example.com/audio/welcome.wav",
"batchid": "BATCH001",
"callfrom": "233276128036",
"callto": "233276128037",
"clientid": "MSG123456789"
}
| Field | Type | Description |
|---|---|---|
| channelid | string | The unique call ID from Wigal (same as received in callback) |
| action | string | The action to perform (see Action list below) |
| actiondata | string | Any required data depending on the action. For PLAY and RECORD actions, this must be an accessible audio URL (WAV format: mono, a-law, 8KHz, 64kbps) |
| batchid | string | The same batch ID from Wigal (same as received in callback) |
| callfrom | string | The caller ID (same as received in callback) |
| callto | string | The destination number (same as received in callback) |
| clientid | string | The message ID from the initial call (same as received in callback) |
What Are The Benefits?
- Real-time Control: Control the interactive voice call flow in real-time based on call events.
- Dynamic Interactions: Create dynamic voice interactions that respond to user input and call state.
- Automation: Automate complex voice workflows without manual intervention.
- Reliability: Receive real-time updates about call status and events.
In summary, a Voice Callback URL is essential for implementing interactive voice calls, providing real-time event notifications and enabling dynamic call flow control.