Webhook

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.

Setting up the integration in Ringotel Shell 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.

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"
  }
}

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"
  }
}

UpdateCallRecording

Sent after each call if voice recording is enabled in the Ringotel app.

Example

{
  "method": "UpdateCallRecording",
  "api_token": "",
  "params": {
    "call_recording_url": "https://uk.ringotel.co/public/LL2uIbd5NcBZLHGa.wav",
    "call_id": "1729693708182-2d1c3de3d3772cdc1f"
  }
}

Parameters list

“connection_name”: string

Ringotel connection name.

“connection_id”: string

Ringotel connection ID.

“extension”: string

Ringotel Extension associated with a call.

“user_id”: string

Ringotel user ID associated with a call.

"activity_type": "inbound" | "outbound"

Activity type description, stores the direction of a call. It has two possible values "inbound" or "outbound".

“domain”: string

Ringotel organization domain.

“call_start”: number

Call start timestamp in EPOCH format (milliseconds from Jan 1, 1970).

“call_end”: number

Call end timestamp in EPOCH format (milliseconds from Jan 1, 1970).

"calling_number": string

Calling party number.

"called_number": string

Called party number.

"call_duration": number

Call duration (in seconds).

“call_id”: string

Call ID.

"call_cause": string

SIP hangup cause code.

"call_url": string

Unencoded URL to access the call recording.

"call_subject": string

Call activity subject.

"call_description": string

Call activity comment.