Application
An Application is a set of Answer, Hangup, and Message URLs that help you control your incoming calls and messages.
API Endpoint
Answer URL
Plivo requests this URL for a valid Plivo XML element on an incoming call. The XML returned by this URL determines the flow of the call. For example, if you want to play a message on an incoming call to a Plivo number, the URL must return the XML as shown in the example response.
Plivo requests the Answer URL with the following parameters:
Parameters Plivo sends to the Answer URL
| Name | Type | Description |
|---|---|---|
| CallUUID | string | A unique identifier for this call. |
| From | string | The phone number of the party that initiated the call along with the country code. For inbound calls, this is the caller’s caller ID. For outbound calls, this is the caller ID specified in the API request. |
| To | string | The phone number of the called party with the country code. For inbound calls, this is your Plivo number. For outbound calls, this is the destination number provided in the API request. |
| ForwardedFrom | string | Set only when the call received by Plivo is a forwarded call. Its value depends on the caller’s carrier and may not always be present. |
| CallStatus | string | Indicates the call’s status: ringing, in-progress, or completed. For outbound calls, it may also be busy, failed, timeout, or no-answer. |
| Direction | string | Indicates the direction of the call. Typically inbound for incoming calls and outbound for calls made using the Call API. |
| ALegUUID | string | A unique identifier for the first leg of the call in outbound scenarios. Not present for inbound calls. |
| ALegRequestUUID | string | A unique request identifier returned by Plivo for an outbound call initiated via API. Not present for inbound calls. |
Hangup URL
Plivo will make an HTTP request to this URL when the call is hung up. The following parameters will be sent to the Hangup URL:
Parameters Plivo sends to the Hangup URL
| Name | Type | Description |
|---|---|---|
| CallUUID | string | A unique identifier for this call. |
| From | string | The phone number of the party that initiated the call with the country code. For inbound calls, this is the caller’s caller ID. For outbound calls, it’s the caller ID specified in the API request. |
| To | string | The phone number of the called party with the country code. For inbound calls, it’s your Plivo number. For outbound calls, it’s the destination number provided. |
| ForwardedFrom | string | Set only when the call received by Plivo is a forwarded call. Its value depends on the caller’s carrier and may not always be present. |
| CallStatus | string | Indicates the call status: ringing, in-progress, or completed. For outbound calls, may also be busy, failed, timeout, or no-answer. |
| Direction | string | Indicates call direction. Typically inbound (ringing state) or outbound (answered state via API). |
| ALegUUID | string | Unique identifier for the first leg of an outbound call. Not present for inbound calls. |
| ALegRequestUUID | string | Unique request identifier for an outbound call initiated via API. Not present for inbound calls. |
| Duration | string | Duration of the call in seconds. |
| BillDuration | string | Billed duration of the call in seconds. |
| HangupCauseName | string | Reason for the call hangup. See this guide for more details. |
| HangupCauseCode | integer | Unique code representing the hangup cause. See this guide for the full list. |
| HangupSource | string | Entity that triggered the hangup. Possible values: Caller, Callee, Plivo, API Request, Answer XML, Error, Unknown. More info in this guide. |
Message URL
Plivo will send all incoming messages to this URL. We expect to receive a HTTP status code of 200 from this URL. If a non 200 code is returned, we would keep retrying this URL once every 5 minutes for the first hour and then once every hour for 24 hours. Plivo will drop the message after 24 hours of receiving non 200 codes.
The following parameters will be sent to the Message URL.
Parameters Plivo sends to the Message URL
| Name | Type | Description |
|---|---|---|
| From | string | The source number of the incoming message. This will be the number of the person sending a message to a Plivo number. |
| To | string | The number to which the message was sent. This will the your Plivo number on which the message has been received. |
| Type | string | Type of the message. This will always be sms. |
| Text | string | The content of the message. |
| MessageUUID | string | A unique ID for the message. Your message can be uniquely identified on Plivo by this ID. |