Create Leg

POST

https://{{base_url}}/v2/accounts/{{AccountSID}}/legs

Parameter Name	Mandatory / Optional	Value	Description
contact_uri	Mandatory	String	Can use “sip:” or a indian phone number with 0 or with country prefix
network_type	Optional	String. {“pstn”, “voip”}. Default = “pstn”	Should be voip when “sip:” used in contact_uri, else “pstn”
exophone	Mandatory	String	Can use “sip:” or a indian phone number with 0 or with country prefix
custom_param	Optional	String	User specified custom parameter. Will be sent back with external events
leg_event_endpoint	Mandatory	String	grpc endpoint to provide events to.
time_limit	Optional	Integer (in seconds). Default = 4 hours	Total time for leg
timeout	Optional	Integer (in seconds). Default = 30 seconds	Timeout for creating a leg. Time from which the leg is initiated to when the leg is picked up
setup_timeout	Optional	Integer (in seconds). Default = 30 seconds	The time period from channel initialization till the Channel starts Ringing. Setup Timeout is the max allowed Setup Time
ring_timeout	Optional	Integer (in seconds). Default = 30 seconds	The time period from when the channel starts ringing till it is answered.
requested_dc_code	Optional	String	If provided the leg would be created from the given DC Code
requested_nso_code	Optional	String	If provided the leg would be created from the given NSO Code
reference_leg_sid	Optional	String	If provided the leg would be created from the same location as the reference leg sid. Note: If two or more legs are being bridged, they should be co-located. This can be achieved by passing the reference_leg_sid parameter while creating subsequent legs which are to be bridged with the first leg
amd_enable	Optional	Bool (default : false)	If set to true,it will detect whether the call is answered by a machine.
async_amd	Optional	Bool (default : false)	Applicable only when amd_enable is true. If async_amd is set to false, it will send answered_by field in leg_answered event. If async_amd is set to true ,it will send answered_by in a separate external event : amd_result_success on successful amd detection.
priority	Optional	String (default: normal)	Applicable only when CPS (calls per second) throughput control is enabled for account and telco pair CPS throughput control is not enabled by default Allowed values are normal or high If a call is enqueued as a result of this , then the response contains status as enqueued in the response

Sample Request Body
JSON

{
    "contact_uri": "09163816621",
    "exophone": "08030752400",
    "leg_event_endpoint": "grpc://127.0.0.1:9001",
    "network_type" : "pstn",
    "timeout": 200,
    "time_limit": 200
}

Response Data:

Parameter Name	Type & Value
leg_sid	string
created_at	string
account_sid	string
contact_uri	string
network_type	string
exophone	string
custom_param	string / null
leg_event_endpoint	string

Sample Response
JSON

{
    "request_id": "811b113c561a4d35bd8520112eb629f7",
    "method": "POST",
    "http_code": 202,
    "response": {
        "error_data": null,
        "data": {
            "leg_sid": "2QYATxQ9t4UKcUwcqJClSa9OEZ400000",
            "created_at": "2023-05-31 08:02:32.608752571 +0000 UTC",
            "account_sid": "exotel60",
            "contact_uri": "09163816621",
            "network_type": "pstn",
            "exophone": "08030752400",
            "custom_param": null,
            "leg_event_endpoint": "127.0.0.1:9001"
        }
    }
}

External Events:

Key	Type	Sample Value
event_sid	string	2QmI6NeiCjDaz5egUwkVlJCOtUQ00000
event_type	string	leg_lifecycle_event
event_name	string	incoming_leg
event_timestamp	object
- seconds	integer	1685952153
- nanos	integer	285423183
event_data	object
- data	object
data	object
- account_sid	string	exotel60
- caller_id	string	8030752400
- contact_uri	string	7417712343
- date_created	string	2023-06-05T08:02:33.214702529Z
- date_updated	string	2023-06-05T08:02:33.214702529Z
- dc_code	string	101
- direction	string	inbound
- exophone	string	8030752400
- leg_sid	string	2QmI6PngBZ7gc3VXJnOzCVBLsNP00000
- network_type	string	pstn
- nso_code	string	a8140aaa-ce40-11ed-9a09-0242ac110003
- start_time	string	2023-06-05T08:02:33.214702529Z
- state	string	ringing
- time_limit	integer	14400

Events Create Leg can generate:

Event Name	EventType	event_data.data	event_data.error	data
“leg_connecting”	leg_lifecycle_event	None	-	"state": "connecting"
“leg_ringing”	leg_lifecycle_event	None	-	"state": "ringing"
“leg_answered”	leg_lifecycle_event	None	-	"state": "connected" (if amd_enable is true ) "answered_by":"BEEP/ HUMAN / MACHINE"
“amd_result_success”	leg_action_event	None		(If amd_enable, async_amd both is set to true ) "state": "connected", "answered_by":"BEEP/ HUMAN / MACHINE"
“leg_terminated”	leg_lifecycle_event	"hangup_cause_code": 16, "sip_cause_code": 487, "sip_reason": "..."	“error_code”: .., “message”:”...”, “description”:”...”	"state": "terminal", "terminal_status": "completed/ busy/ no-answer/ failed"
“leg_failed_to_create”	leg_lifecycle_event	None	“error_code”: .., “message”:”...”, “description”:”...”	"state": "terminal", "terminal_status": "failed"

Sample event (incoming leg):
JSON

{
    "event_sid": "2K8DQQuKWiXhXdfpMnXJYKVoTdB",
    "event_type": "leg_lifecycle_event",
    "event_name": "leg_incoming",
    "event_timestamp": {
        "seconds": 1673347299,
        "nanos": 607761576
    },
    "data": {
        "account_sid": "exotel60",
        "caller_id": "08030752400",
        "contact_uri": "09163816622",
        "date_created": "2023-01-10T10:41:39.607712401Z",
        "date_updated": "2023-01-10T10:41:39.607712401Z",
         "dc_code": "101",
        "direction": "inbound",
        "exophone": "08030752400",
        "leg_sid": "2K8DQQr2eoPW6HXJej7VesxsTUy00000",
        "network_type": "pstn",
         "nso_code": "9988fd96-ce41-11ed-9a09-0242ac110003",
        "start_time": "2023-01-10T10:41:39.03987348Z",
        "state": "ringing",
        "time_limit": 14400
    }
}

Sample event (Outgoing leg):
JSON

{
  "event_sid": "2Qmm2gI1sRmNkiGNyREGKHv2PnG00000",
  "event_type": "leg_lifecycle_event",
  "event_name": "leg_connecting",
  "event_timestamp": {
    "seconds": 1685966925,
    "nanos": 743609442
  },
  "data": {
    "account_sid": "exotel60",
    "caller_id": "8030752501",
    "contact_uri": "07417712343",
    "custom_param": "MD_LEGS",
    "date_created": "2023-06-05T12:08:45.521094309Z",
    "date_updated": "2023-06-05T12:08:45.631124146Z",
    "dc_code": "101",
    "direction": "outbound",
    "exophone": "08030752400",
    "leg_sid": "2Qmm2j6Y9MfjJfQMNg61K8DaKxv00000",
    "network_type": "pstn",
    "nso_code": "9988fd96-ce41-11ed-9a09-0242ac110003",
    "start_time": "2023-06-05T12:08:45.630677211Z",
    "state": "connecting",
    "time_limit": 14400
  }
}

GET Leg

GET

https://{{base_url}}/v2/accounts/{{AccountSID}}/legs/{{LegSID}}

Request Query Parameters: All below query parameters are optional:
bridge_status, recording_status, tx_audio_status, rx_audio_status, hold_status, gather_status, play_status

Example Request
cURL

https://{{base_url}}/v2/accounts/{account_sid}/legs/{leg_sid}?fields=bridge_status,recording_status,hold_status,gather_status,play_status

Response:

Parameter Name	Type
leg_sid	string
account_sid	string
contact_uri	string
exophone	string
caller_id	string
direction	string
network_type	string
time_limit	string
state	string
terminal_status	string
date_created	string
date_updated	string
start_time	string
end_time	string
on_call_duration_ms	int
additional_info	Object (Present based upon Query Parameters provided)
- recording_status	string
- hold_status	string
- gather_status	string
- play_status	string
- bridge_status	string

Sample Response
JSON

{
    "request_id": "ce7b872225b348f09e80115c1ff569a3",
    "method": "GET",
    "http_code": 200,
    "response": {
        "error_data": null,
        "data": {
            "leg_sid": "2QYATxQ9t4UKcUwcqJClSa9OEZ400000",
            "account_sid": "exotel60",
            "contact_uri": "09163816621",
            "exophone": "08030752400",
            "caller_id": "8030752501",
            "direction": "outbound",
            "network_type": "pstn",
            "time_limit": 200,
            "state": "connected",
            "date_created": "2023-05-31T08:02:32.608752571Z",
            "date_updated": "2023-05-31T08:03:06.207740524Z",
            "start_time": "2023-05-31T08:02:32.678845375Z",
            "additional_info": {
                "recording_status": "not_recording",
                "hold_status": "normal",
                "gather_status": "not_gathering",
                "play_status": "not_playing",
                "bridge_status": "not_bridged"
            }
        }
   }
}

External Events: None

POST Bridge

POST

https://{{base_url}}/v2/accounts/{{AccountSID}}/bridges

Parameter Name	Mandatory / Optional	Value	Description
leg_sids	Mandatory	Array of Strings:[""]	List of legSIDs of the active legs, that we want to be a part of the bridge.
bridge_event_endpoint	Mandatory	String	Endpoint to send events.
absorb_dtmf	Optional	Boolean	If true, DTMF tones from all legs on the bridge will be absorbed and not passed to others

Sample Request Body
JSON

{
    "leg_sids":["2tdAWSaOchu4VxFIQqf4IBm0EMH00000", "2tdAcyul4xmM2zXiK8nkYYmxrsg00000"],
    "absorb_dtmf": true,
    "bridge_event_endpoint": grpc://grpcEndpoint.com:port"
}

Response:

Parameter Name	Type
bridge_sid	string
created_at	string
account_sid	string
leg_sids	array[string] (optional)
bridge_event_endpoint	string

External Events:

Event Name	Event Type	Event Data	Data
“bridge_created”	bridge_lifecycle_event	None	bridge.state: active
“bridge_failed_to_create”	bridge_lifecycle_event	event_data: error: “error_code” : …, “message”: “…”, “description”: ”...”	bridge.state: terminal
“bridge_terminal”	bridge_lifecycle_event	None	bridge.state: terminal
“leg_joined_bridge”	leg_lifecycle_event	event_data: bridge_sid: "2QmZ1EgVpS25l4ujkjGjCEsnajY00000"	leg.state: connected
“leg_left_bridge”	leg_lifecycle_event	event_data: bridge_sid: "2QmZ1EgVpS25l4ujkjGjCEsnajY00000"	leg.state: connected

Sample Event
JSON

{
  "event_sid": "2QmZ1DghXqX1iU9PUrfexRHkECU00000",
  "event_type": "bridge_lifecycle_event",
  "event_name": "bridge_created",
  "event_timestamp": {
    "seconds": 1685960499,
    "nanos": 272434000
  },
  "data": {
    "account_sid": "exotel60",
    "date_created": "2023-06-05T10:21:39.079165726Z",
    "date_updated": "2023-06-05T10:21:39.15787587Z",
    "sid": "2QmZ1EgVpS25l4ujkjGjCEsnajY00000",
    "start_time": "2023-06-05T10:21:39.15787587Z",
    "state": "active"
  }
}

Sample event (Joined Bridge):
JSON

{
  "event_sid": "2QmZ1FhpEDIcs6YAhSQdXnbUxkf00000",
  "event_type": "leg_lifecycle_event",
  "event_name": "leg_joined_bridge",
  "event_timestamp": {
    "seconds": 1685960499,
    "nanos": 447549903
  },
  "event_data": {
    "data": {
      "bridge_sid": "2QmZ1EgVpS25l4ujkjGjCEsnajY00000"
    }
  },
  "data": {
    "account_sid": "exotel60",
    "caller_id": "8030752501",
    "contact_uri": "07417712343",
    "custom_param": "MD_LEGS",
    "date_created": "2023-06-05T10:21:20.058556349Z",
    "date_updated": "2023-06-05T10:21:39.407218765Z",
    "dc_code": "101",
    "direction": "outbound",
    "exophone": "08030752400",
    "leg_sid": "2QmYyp1kD1bbAKxWjNxAAnlGMn100000",
    "network_type": "pstn",
    "nso_code": "9988fd96-ce41-11ed-9a09-0242ac110003",
    "start_time": "2023-06-05T10:21:20.133846202Z",
    "state": "connected",
    "time_limit": 14400
  }
}

GET Bridge

GET

https://{{base_url}}/v2/accounts/{{AccountSID}}/bridges/{{BridgeSID}}

Request Query Parameters: None

Response:

Parameter Name	Type & Value
sid	string
account_sid	string
state	string
terminal_status	string (optional)
date_created	string
date_updated	string
start_time	string (optional)
end_time	string (optional)
active_legs	array[string]
leg_sids	array[string]

JSON

{
“request_id”: “783c02db875640249b472ac8e8e29865”,
“method”: “GET”,
“http_code”: 200,
“response”: {
“error_data”: null,
“data”: {
“sid”: “2Qs5eQdcVkuBQE6xLlnTCVpPeqk00000”,
“account_sid”: “exotel60”,
“state”: “terminal”,
“terminal_status”: “completed”,
“date_created”: “2023-06-07T09:19:02.745010493Z”,
“date_updated”: “2023-06-07T09:19:36.803345557Z”,
“start_time”: “2023-06-07T09:19:02.840753144Z”,
“end_time”: “2023-06-07T09:19:36.803345557Z”,
“active_legs”: [],
“leg_sids”: [
“2Qs5cqrz0iCTiJjrds49cx9PWTh00000”,

                "2Qs4cqrz0iCTiJjrds50cx9PWTh00000",
            ]
        }
    }
}

External Events: None

PUT Bridge

PUT

https://{{base_url}}/v2/accounts/{{AccountSID}}/bridges/{BridgeSID}

Request Body Parameters:

Parameter Name	Mandatory / Optional	Value
action	Mandatory	"stop"

Sample Request Body
JSON

{
    "action":"stop"
}

Response:

Parameter Name	Type & Value
bridge_sid	string
created_at	string
account_sid	string
bridge_event_endpoint	string
action	"stop"

Sample Response
JSON

{
"request_id": "fbc0f97cb3404375a07272f678635480",
"method": "PUT",
"http_code": 202,
"response": {
"error_data": null,
"data": {
"bridge_sid": "2Qs5eQdcVkuBQE6xLlnTCVpPeqk00000",
"created_at": "2023-06-07 09:22:22.099891627 +0000 UTC",
"account_sid": "exotel60",
"bridge_event_endpoint": "127.0.0.1:9001",
"action": "stop"
}
}
}

External Events:

Event Name	Event Type	Event Data	Data
“leg_left_bridge”	leg_lifecycle_event	None	leg.state: connected
“bridge_terminated”	bridge_lifecycle_event	None	bridge.state: terminal
“bridge_failed_to_stop”	bridge_lifecycle_event	None	bridge.state: active

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More

Create Leg

External Events:

Events Create Leg can generate:

GET Leg

Response:

POST Bridge

GET Bridge

PUT Bridge