Voice Callbacks

    Overview

    In this tutorial, you’ll learn how callbacks can help you analyze the different call statuses of an ongoing call and manage call flow based on the values received in callback events.

    Get Started with Webhooks

    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. They can be integrated into web services without adding new infrastructure.

    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.

    The webhooks you integrate with Plivo are usually triggered by incoming calls or incoming messages. During these events, 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 app) that can accept these HTTP requests.

    Call Status related Webhooks

    Webhooks for Outbound Calls

    Here are the URLs you need to define to use Plivo’s Voice API to make an outbound call from your web application, manage the call flow, and receive status callback events on your application server.

    URLs specific to API request payload

    The URLs 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 other URLs 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. For example, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as answer_url to test your first outgoing call. In that case a valid XML response, using the Speak verb, would be:

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

      As you can tell, the XML snippet above holds instructions to say “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of Plivo XML verbs and their details in the XML Reference section of our documentation.

    • fallback_url : Plivo invokes this URL if the answer_url is not reachable.
    • ring_url : An optional URL Plivo can notify once the call starts ringing.
    • hangup_url : An optional URL Plivo can notify once the call is disconnected.

    Plivo can also send parameters with an HTTP request during the different 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 sent 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 : 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.

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

    Webhooks for Inbound Calls

    Webhooks can be used with Plivo numbers to receive callbacks for incoming calls. When a voice-enabled Plivo phone number receives an incoming call, Plivo will send 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, you have all the information related to the inbound call 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 : An optional URL Plivo can notify once 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.

    Handle Callbacks in Your Web Application

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

    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 the 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 can validate the callbacks that your server URL receives. All requests made by Plivo to your server URLs consist of an 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 guide.