About Call Events

Our /calls service will be available soon! Read about call features and functions below but please don't try them out just yet.

When your application receives or manages a phone call, it will receive HTTP notifications as call events occur.

Call event notifications are sent in the following situations:

  • A phone call has been directed to your application (for this to happen, you must forward incoming phone calls to your app)
  • An asynchronous job has finished processing
  • A call being managed by your application has disconnected—using the hangup command, a DELETE request, or the other party has ended the call

Event notifications are sent in JSON format via HTTP POST to the Main URL defined for your application. If your Main URL is unable to process the request, the service will fail over to the Fallback URL, if defined for your app. Please see Systems and Requirements for help with configuring app servers to receive Phone.com API POST events.

Note: Your application will always receive a notification when a call has been disconnected, even when the call ended due to a hang-up command. When you execute an asynchronous job that contains a hang-up command, your application will receive two event notifications where the status is hangup; one notification containing the results of your job, and a second to indicate that the call has ended. This can be confusing because the status of the call object in both call events will be hangup.

JSON Structure of a Call Notification

    "response": {
        "call": {
            "resource_id": "55bb5e92-7436-11e3-b573-d5e99f111111",
            "application_id": "4556e204-05de-11e3-bf32-cdee48888888",
            "batch_id": "4556e204-05de-11e3-bf32-cdee42222222",
            "to": "+15555552345",
            "from": "+15555551234",
            "status": "hangup",
            "hangup_cause": "command",
            "duration": 10,
            "schedule_start": "2013-12-24T03:16:25",
            "schedule_start_epoch": 1387854985,
            "schedule_end": "2013-12-24T03:27:25",
            "schedule_end_epoch": 1387854985,
            "time_start": "2013-12-24T03:16:29",
            "time_start_epoch": 1387854989,
            "time_end": "2013-12-24T03:16:39",
            "time_end_epoch": 1387854999,
            "keep-state": "eyAibXkiOiJiYXNlIDY0IGVuY29kZWQgSlNPTiBvYmplY3QiIH0="
        "commands": [
                "command": "dial",
                "status": 200,
                "result": "connected"
                "command": "say",
                "status": 200,
                "result": "ok"
                "command": "hangup",
                "status": 200,
                "result": "ok"

Event Notification Fields

Parameter Type Description
service String Service that is sending the notification. For call-related events, this will always be calls.
call Object Call object representing the current status and parameter of the call.
commands Array This parameter is only populated when the notification is in response to the execution of an asynchronous job, and contains an array of call commands executed during job processing and their results.

Learn More: