The Ringotel Webhook Integration provides a convenient way to automate workflows by sending HTTP requests to a specified webhook URL when certain events occur within the platform. This feature allows you to seamlessly integrate Ringotel with third-party applications, services, or internal systems by notifying them in real-time when key events are triggered.
Note:
Webhook notifications are only triggered by external calls. Calls to and from numbers that start with * or are less then 4 digits would not trigger the webhook notifications.
Setting up integration in Ringotel portal
Sign into your Ringotel admin portal at https://shell.ringotel.co and navigate to an organization → Integrations tab → click Enable Integration on the Webhook card.
Specify your Webhook URL and API token and click Save & Continue.
Note:
Specifying the API token is optional. It will be sent in the body of each request to the Webhook URL in the “api_token” parameter.
Receiving Requests on the Webhook
Currently, the integration can send the following requests:
StartCallActivity
Sent when a call is started.
For inbound calls, this event is sent when calls hit a Ringotel User.
For outbound calls, this event is sent when a Ringotel user initiates a call.
Example:
{
"method": "StartCallActivity",
"api_token": "5c2d7008-a4b9-4eec-b549-e82804521e9a",
"params": {
"connection_name": "PBX",
"extension": "500",
"user_id": "17295348437628309790",
"connection_id": "17295345566567084859",
"activity_type": "inbound",
"domain": "newcompany123",
"call_start": 1729690611587,
"called_number": "500",
"caller_number": "353212028252",
"call_id": "1729693708182-2d1c3de3d3772cdc1f"
}
}
Create Activity
Sent when the other party picks up the phone and the call is connected.
Example:
{
"method": "CreateActivity",
"api_token": "",
"params": {
"connection_name": "Default connection",
"extension": "1001",
"user_id": "17292448538752201903",
"connection_id": "17292448416457942084",
"activity_type": "inbound",
"domain": "webhookint",
"call_start": 1762775285203,
"called_number": "1001",
"caller_number": "18295701330",
"call_id": "1762775285203-eb696040d8740d6fb4"
}
}
StopCallActivity
Sent when a call is ended by either party or when the call ends without an answer.
Example:
{
"method": "StopCallActivity",
"api_token": "5c2d7008-a4b9-4eec-b549-e82804521e9a",
"params": {
"extension": "500",
"call_end": 1729693741839,
"call_id": "1729693708182-2d1c3de3d3772cdc1f",
"call_duration": 27,
"connection_name": "PBX",
"user_id": "17295348437628309790",
"connection_id": "17295345566567084859",
"activity_type": "inbound",
"domain": "newcompany123",
"call_cause": "0",
"call_start": 1729693708166,
"called_number": "500",
"caller_number": "353212028252"
}
}
UpdateActivity
Sent when a call comment or call subject is updated in the Ringotel app.
Example:
{
"method": "UpdateActivity",
"api_token": "",
"params": {
"call_subject": "Audio Check",
"call_summary": "The caller is testing their audio and performing a sound check by counting and saying 'hello'.",
"call_transcription": "https://us1.ringotel.co/public/...DV1sR8.json",
"call_id": "1729693708182-2d1c3de3d3772cdc1f"
}
}
UpdateCallRecording
Sent after each call if voice recording is enabled in the Ringotel app.
Example:
{
"method": "UpdateCallRecording",
"api_token": "",
"params": {
"extension": "1001",
"called_number": "1001",
"caller_number": "353212028252",
"call_recording_url": "https://uk.ringotel.co/public/LL2uIbd5NcBZLHGa.wav",
"call_id": "1729693708182-2d1c3de3d3772cdc1f"
}
}
Parameters list
Parameter name | Type | Description |
connection_name |
| Ringotel connection name. |
connection_id |
| Ringotel connection ID. |
extension |
| Ringotel Extension associated with a call. |
user_id |
| Ringotel user ID associated with a call. |
activity_type |
| Activity type description, stores the direction of a call. It has two possible values |
domain |
| Ringotel organization domain. |
call_start |
| Call start timestamp in EPOCH format (milliseconds from Jan 1, 1970). |
call_end |
| Call end timestamp in EPOCH format (milliseconds from Jan 1, 1970). |
calling_number |
| Calling party number. |
called_number |
| Called party number. |
call_duration |
| Call duration (in seconds). |
call_id |
| Call ID. |
call_cause |
| SIP hangup cause code. |
call_url |
| Unencoded URL to access the call recording. |
call_subject |
| Call activity subject. |
call_summary |
| Call activity comment. |
call_transcription |
| If AI Assistant is enabled, contains URL that points to a call transcription in the JSON format. |
Returning custom data in Webhook responses
You can pass custom data in the “initCall” request and then receive this data in the subsequent notifications to your Webhook URL, provided in the Webhook integration settings.
Example "initCall" request
{
"method": "initCall",
"params":{
"from":"511",
"tonumber": "0851344344",
"toname": "Test",
"orgid": "17629027527954336546",
"custom_data": {
"param1": "testValue1",
"param2": "testValue2"
}
}
}
"StopCallActivity" notification to the Webhook
{
"method": "StopCallActivity",
"api_token": "",
"params": {
"call_end": 1762903208319,
"extension": "511",
"user_id": "17629028023247184684",
"activity_type": "outbound",
"call_cause": "0",
"call_start": 1762903182412,
"called_number": "0851344344",
"caller_number": "511",
"call_duration": 19,
"call_id": "1762903182412-ffe4731537a8a93de8"
},
"custom_data": {
"param1": "testValue1",
"param2": "testValue2"
}
}
"UpdateCallRecording" notification
{
"method": "UpdateCallRecording",
"api_token": "",
"params": {
"call_recording_url": "https://uk.ringotel.co/public/DLA35vQKGC....AJKEqkB4nHybsEIF8.wav",
"call_id": "1762903182412-ffe4731537a8a93de8"
},
"custom_data": {
"param1": "testValue1",
"param2": "testValue2"
}
}