Using Call Commands

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

The Phone.com API /calls service extends our standard phone features, letting you initiate, control and complete phone calls as needed using the commands documented in this topic.

Use the information below in conjunction with our /calls reference topic to build call functions into your applications.

In This Topic:


What Are Call Commands?

Your application will use call commands to manage and control the events of a phone call. For example, when a new call is routed to your application, your app can choose to either answer the call by sending the answer command or reject the call by sending the hangup command.

Other call commands allow you to perform actions like playing an audio file, speaking a text greeting, or requesting and sending keytones (DTMF) on the call.

Commands Supported in the /calls Service

Below is the list of call commands currently supported, along with the HTTP methods (PUT and POST) supported for each command.


Call Command Supported for POST Supported for PUT
dial Yes (Required). Command must be first. Can only be a single dial command per call. Invalid
answer Invalid Yes. If specified, answer must be first; Required if call status is ringing; Can only be a single answer command per call.
play Yes. Call status must be ready. Yes. Call status must be ready.
say Yes. Call status must be ready. Yes. Call status must be ready.
get_dtmf Yes. Call status must be ready. Yes. Call status must be ready.
send_dtmf Yes. Call status must be ready. Yes. Call status must be ready.
hold Yes. Call status must be ready. Yes. Call status must be ready.
unhold Yes. Call status must be ready. Yes. Call status must be ready.
hangup Yes. If specified, this command must be last. Yes. If specified, this command must be last.

Each of these commands is detailed below, with code examples and parameter descriptions.


dial

This command creates a new outbound call to the number specified in the to argument. The callee will receive an inbound call with the from argument as the Caller ID. After successful execution the call status will change to ready.

This command can only be used in HTTP POST requests. When used, it must be the first command in the commands array.

Example


{
    "dial" : {
       "to" : "+12345678900",
       "from" : "+12345678901",
       "timeout" : 100,
       "schedule_start" : "2013-12-31T23:00:00",
       "schedule_expire" : "2013-12-31T23:59:59"
    }
}


Request Fields

Parameter Type Description
to String or Array of Strings Phone number or array of phone numbers to call (E.164 format)
from String Phone number to display as the Caller ID, in (E.164 format)
timeout (Optional) Integer Number of seconds to wait for the call to connect. Default: 30 sec. Call automatically ends after the time set.
schedule_start (Optional) ISO 8601 Date/time when the call should be sent
schedule_expire (Optional) ISO 8601 Date/time when the pending call request should be canceled, if our system cannot process the request in time

Response Fields

Response Status Type Description
200 Integer Command completed successfully. The call is now connected and ready for additional commands.
408 Integer Command failed because the call was not answered prior to the timeout
409 Integer Command failed because the phone number was busy
424 Integer Command was skipped because a previous command failed or a dependency was not met
503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


answer

This command answers a new, inbound call. After successful execution, the call status will change to ready. This command can only be used in HTTP PUT requests. When used, it must be the first command in the commands array.

Valid for execution on calls with a status of ringing.

Example


{
    "answer" : {}
}


Request Fields

None.

Response Fields

Response Status Type Description
200 Integer Command completed successfully. The call is now connected and ready for additional commands.
424 Integer Command was skipped because a previous command failed or a dependency was not met
503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


play

This command plays an audio file on a call. The resource_id or name can correspond to any media resource in your account. Audio files can be uploaded and managed using the /media service.

Valid for execution on calls with a status of ready.

Example


{
    "play" : {
       "resource_id" : "4556e204-05de-11e3-bf32-cdee47777777",
       "repeat" : 100
    }
}


Request Fields

Parameter Type Description
resource_id String Phone number to call. Required, unless name is specified
name (Optional) String Name of the media file to play (refer to: GET /media/UUID)
repeat (Optional) Integer Number of times to repeat the playback of this file. Minimum 1, maximum 100.

Response Fields

Parameter Type Description
resource_id String Phone number to call
repeat Integer Number of times the media file was repeated
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


say

This command plays an audio file on a call. The resource_id or name can correspond to any media resource in your account. Audio files can be uploaded and managed using the /media service.

Valid for execution on calls with a status of ready.

Example


{
    "say" : {
        "text" : "<text to convert>",
        "voice" : "<

Request Fields

Parameter Type Description
text String Text to convert to audio
voice (Optional) String Name of the Phone.com text-to-speech voice to use (refer to: POST /media)

Response Fields

Parameter Type Description
text String Text argument
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


get_dtmf

This command begins listening for DTMF tones on a call, and reports them back to the application.

The control_key is an optional DTMF key that signifies the end of DTMF input from the callee. When this key is detected, the command is marked as completed and the previous DTMF tones collected are returned.

If no DTMF tones are detected prior to the timeout, the command will fail. If DTMF tones are detected, they will be returned in the result field of the command response.

The commands field holds a list of commands that will be processed while waiting for user input. The commands will stop execution once the user begins sending DTMF.

Valid for execution on calls with a status of ready.

Example


{
    "get_dtmf" : {
        "control_key": "#",
        "timeout": 15,
        "commands": [
            {
                "play": {
                    "resource_id": "4556e204-05de-11e3-bf32-cdee47777777"
                }
            },
            {
                "say": {
                    "text": "say this text after playing the audio file",
                    "voice": "allison"
                }
            }
        ]
    }
}


Request Fields

Parameter Type Description
control_key (Optional) String Single DTMF key to listen for that signifies the end of current DTMF input
timeout (Optional) Integer Amount of time to wait for DTMF to start being entered by the callee. Default: 15 seconds.
commands (Optional) Array of commands List of commands to execute while waiting for the callee to begin sending DTMF. Valid commands are play and say.

Response Fields

Parameter Type Description
result String DTMF tones received
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


send_dtmf

This command sends DTMF tones on a call.

Valid for execution on calls with a status of ready.

Example


{
    "send_dtmf" : {
       "dtmf": "1234567890*#"
    }
}


Request Fields

Parameter Type Description
dtmf String DTMF keys to send

Response Fields

Parameter Type Description
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


hold

This command places a call on hold. After successful execution, the call status will change to hold.

The timeout argument specifies the maximum number of seconds that the call can remain on hold. Once that timeout has been reached, the call will be terminated.

Valid for execution on calls with a status of ready.

Example


{
    "hold" : {
       "hold_music": "4556e204-05de-11e3-bf32-cdee41112222",
       "timeout": 900
    }
}


Request Fields

Parameter Type Description
hold_music (Optional) UUID Resource ID for the media file to use as hold music. Default: Uses default Phone.com hold music.
timeout (Optional) Integer The maximum time to allow a caller to stay on hold. Minimum value: 10, Maximum value: 3600, Default: 900.

Response Fields

Parameter Type Description
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


unhold

This command will remove a call from hold. After successful execution the call status will change to ready.

Valid for execution on calls with status: hold

Example


{
    "unhold" : {}
}


Request Fields

None.

Response Fields

Parameter Type Description
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully. The call is now connected and ready for additional commands.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


hangup

This command ends a call. After successful execution the call status will change to hangup.

Valid for execution on calls with status: hold

Example


{
    "hangup" : {}
}


Request Fields

None.

Response Fields

Parameter Type Description
status Integer Response code will be one of the following:
Visual spacer 200 Integer Command completed successfully.
Visual spacer 424 Integer Command was skipped because a previous command failed or a dependency was not met
Visual spacer 503 Integer Internal error occurred while processing the command

Back to Commands Supported in the /calls Service.


Learn More: