Voice callbacks

Plivo makes HTTP requests to webhooks during different states of a voice call. These callbacks can help you analyze the call statuses of an ongoing call and manage call flow based on the values you receive from callback events.

Webhooks are user-defined event-based HTTP callbacks that operate based on the concept of event reaction. They’re a helpful tool to use when you want to create instant and real-time notifications.

Plivo uses webhooks to make it possible to track the status of your voice calls. For every outbound and inbound call, Plivo sends a status update to a URL you configure for receiving callback events. You can read and store the information on your server for call reporting analysis.

When a webhook is triggered by an event, Plivo makes an HTTP request (POST or GET) to the endpoint URL configured for the webhook. To handle a webhook, you must create a listener (web application) that can accept these HTTP requests.

Call Status related Webhooks

Webhooks for outbound calls

For outbound calls from your web application, you can use callbacks to manage the call flow and receive status events on your application server. Plivo uses webhook callbacks in both Voice API and XML elements:

URLs specific to API request payload

Webhook parameters associated with a Voice API outbound call payload are answer_url, ring_url, fallback_url, and hangup_url. answer_url is a mandatory parameter for outbound API calls; the others are optional. You can configure unique webhook URLs and set the method as either POST or GET to receive call status-related callbacks during different events.

  • answer_url : When a call is answered by the destination number, you can control the call flow with the help of the answer_url set in the API request. Plivo invokes the answer_url specified as soon as the call is answered and expects a valid XML response with instructions to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as answer_url to test your first outgoing call:

      <Response>
  <Speak>Congratulations! You've made your first outbound call!</Speak>
  </Response>

    This XML snippet gives instructions to say, “Congratulations! You’ve made your first outbound call!” to the call recipient.

  • fallback_url : Plivo can invoke this URL if answer_url is not reachable.
  • ring_url : Plivo can notify this URL when the call starts ringing.
  • hangup_url : Plivo can notify this URL when the call is disconnected.

Plivo can also send parameters with an HTTP request during other events of a call so your application can act to continue the call flow or to change it based on the values it receives. For information about the parameters Plivo sends to these URLs and the possible values they can contain, refer to the Callbacks section under Make an outbound call in our Voice API Reference documentation.

URLs specific to XML response from the answer_url of outbound Call API

The URLs most commonly associated with an XML response from the answer_url are action and callbackUrl.

  • action : Plivo expects XML instructions to carry forward the call in response to action requests, which are typically invoked at the end of an XML element’s execution, such as when an IVR input is received from the caller during a GetInput XML execution.
  • callbackUrl : No XML instructions are expected in response to these requests. They serve as webhooks to notify your application server of important events during the course of an XML element’s execution, such as when a conference participant is muted or unmuted.

For more information about the callback parameters sent to action and callbackUrl, refer to the XML elements sections in the XML reference documentation for elements such as Conference, Dial, GetInput, and GetDigits.

Webhooks for inbound calls

You can use webhooks with Plivo numbers to receive callbacks for incoming calls. When a voice-enabled Plivo phone number receives an incoming call, Plivo sends an HTTP request callback (either POST or GET depending on the method set for the webhook) to the URL specified in the application.

In the callback, all the information related to the inbound call is either in the POST request’s body or the GET request’s query parameters. Here are details about the URLs associated with an inbound call to a Plivo number:

URLs specific to the Plivo number’s Voice app

The URLs associated with API payload are Primary Answer URL, Fallback Answer URL, and Hangup URL.

  • Primary Answer URL is a mandatory field for a voice application assigned to a Plivo number; the other URLs are optional. You can configure these fields with unique webhook URLs and set the method as either POST or GET to receive call status-related callbacks during different events.
  • Fallback Answer URL : Plivo invokes this URL if the Primary Answer URL is not reachable.
  • Hangup URL is an optional URL that Plivo can notify when the call is disconnected.

For more information about the parameters you can send to these URLs and the possible values they can contain, refer to the XML request section of our XML Reference documentation.

URLs specific to the XML response from the answer_url

The URLs associated with the XML response from the answer_url are action and callbackUrl.

  • action : XML instructions to carry forward the call are expected in response to these requests. These requests are typically invoked at the end of an XML element’s execution, such as when an IVR input is received from the caller during a GetInput XML execution.
  • callbackUrl : No XML instructions are expected in response to these requests. Such requests serve as webhooks to notify your application server of important events during the course of an XML element’s execution, such as when a conference participant is muted or unmuted.

Check the receive an incoming call guide for more information about how to receive an incoming call on a voice-enabled Plivo phone number.

Handling callbacks in your web application

To handle callbacks in your application, your endpoint should capture HTTP requests and respond to them.

When Plivo sends HTTP request callbacks to a webhook during an event, you should capture the request (POST or GET based on the type you’ve defined for the URL) and respond with a 200 OK response. To process the callback, you can store the data in your database.

Plivo automatically retries webhooks for a certain timeframe if an HTTP 200 status code is not returned. Check the Configurable Callback Retries guide for more information about callback timeouts and retries.

Validating callbacks

To avoid spoof attacks, you should validate the callbacks that your server URL receives. All requests made by Plivo to your server URLs include X-Plivo-Signature-V3, X-Plivo-Signature-Ma-V3, and X-Plivo-Signature-V3-Nonce HTTP headers. You can use these signatures to validate that the request is from Plivo. Read more about signature validation in our Signature Validation guide.