📞
API Docs
  • Welcome
  • NUMBERS / ORDERING
    • List Areas
    • List Numbers
    • Order Numbers - No Cart
    • Delete Numbers
    • Change Call Forward
    • Vanity Tollfree - Search
    • Vanity Toll Free - Order
  • Shopping Cart Ordering
    • Add Number to Cart
    • List Numbers in Cart
    • Delete Number from Cart
    • Complete Order Cart
  • MY INVENTORY
    • List My Nmbers
    • List Call Flows
    • Change CallFlow
    • CDR Records
  • SMS/MMS
    • Send SMS
    • Send MMS
    • Receive SMS/MMS
    • Receive Delivery Receipts
  • Campaigns
    • Submit TollFree Campaign
  • CALL APIS
    • Calls
    • Set Incoming URL
    • Incoming Calls
    • Listing Calls
    • Making Calls
      • Example Code
        • Outbound to Tel#
        • Outbound to SIP Device
        • Example Responses
    • Modifying Live Calls
      • Examples
    • Recordings
      • Get List of Recordings
      • Delete a Recording
  • CALL API MARKUP
    • API Call Markup Language
      • Say
      • Dial
        • Number
        • Client
        • SIP
      • Play
      • Gather
      • Record
      • Hangup
      • Pause
      • Reject
      • Redirect
  • LOOKUPS
    • Carrier and CNAM
  • Number Portability
    • Validate Portability
    • Lookup Port Request
    • Submit Port Request
  • FAXING
    • Create Outbound Fax
    • Lookup Outbound Fax Status
    • List Faxes
    • Download File
  • registered agent
    • List Companies
    • List Registered Agents
    • List Documents
    • Download Document
    • Create Company
    • Delete Company
    • Create Registered Agent
    • Modify Registered Agent
Powered by GitBook
On this page
  • How the Call APIs Interacts with Your Application
  • Call API Request
  • Request Parameters
  • Call API Response
  • Supported MIME Types
  • The Markup Verbs
  1. CALL API MARKUP

API Call Markup Language

Overview

The API Call Markup Language (ACML) represents a set of instructions you can use to tell the Call API what to do when you receive an incoming call.

When someone makes a call to one of your Call API numbers, the service will look up the URL associated with that phone number and make a request to that URL. The Call API will read the markup instructions at that URL to determine what to do: record the call, play a message for the caller, prompt the caller to press digits on their keypad, etc.

An an example, the following will say a short message, and then record the caller’s voice:

<Response>
    <Say voice="woman">Please leave a message after the tone.</Say>
    <Record maxLength="20" />
</Response>

ACML is similar to HTML. Only one ACML document is rendered to the caller at once, but many documents can be linked together to build complex interactive voice applications.

Calls from a Call API number to an outside number are controlled using ACML in the same manner as incoming calls. The initial URL for the call is provided as a parameter to the Call API request you make to initiate the call.

How the Call APIs Interacts with Your Application

Call API Request

The way the Call API passes data to your application depends on the request method for the given URI. If the request method is GET then the data is passed in the query string (the part after the question mark). If the request method is POST then the data is sent as multi-part form data just like when a browser submits a form.

When the Call API makes a request to your application it will include the following data as request parameters.

Request Parameters

Parameter

Description

CallSid

The unique identifier for the call.

AccountSid

Your account id.

From

The phone number of the originator of the call.

To

The phone number of the call recipient.

CallStatus

A descriptive status for the call. The value is one of these:

completed, failed, ringing, in-progress, no-answer, queued, or initiated

ApiVersion

The version of the Call API used to handle this call.

Direction

The direction of the call. The possible values are inbound and outbound-dial.

CallerName

The caller ID for the caller in the case of an inbound call.

Call API Response

In the response to the request from the Call API, you should provide ACML that will instruct our service on how to handle the current call.

MIME Types. Call API supports the MIME types described in the table below.

Supported MIME Types

Parameter

Description

text/xml, application/xml

Call API interprets the returned document as an XML instruction set.

When your application returns the ACML document the root element of the document must always be specified or the parser will complain.

The Markup Verbs

Using combinations of the verbs below allow you to create all kinds of interactive voice and messaging applications.

References to ACML, RCML or CML are all the same.

PreviousDelete a RecordingNextSay

Last updated 4 months ago

Say some words with text to speech

Call someone else, a phone number or other

Play a wav or mp3 file to the caller

Gather digits or words and send them back to your server

Record the current call

Hangup on the call

Pause the call for a moment (maybe to wait for digits)

Reject this call

Redirect this call to another URL

Say
Dial
SIP
Client
Number
Play
Gather
Record
Hangup
Pause
Reject
Redirect