# Table of Contents - [Quickstart guides, use-case guides and reference documentation for our SMS API, Voice API, and more | Plivo](#quickstart-guides-use-case-guides-and-reference-documentation-for-our-sms-api-voice-api-and-more-plivo) - [Get Started with PHP using PHP Server | Plivo Voice](#get-started-with-php-using-php-server-plivo-voice) - [Overview | Plivo API Reference](#overview-plivo-api-reference) - [Get Started with PHP Server | Plivo SMS](#get-started-with-php-server-plivo-sms) - [Zentrunk Quickstart Guide | Plivo](#zentrunk-quickstart-guide-plivo) - [Get Started with Numbers | Plivo Developers](#get-started-with-numbers-plivo-developers) - [Overview | Plivo API Reference](#overview-plivo-api-reference) - [Integrations | Plivo Developers](#integrations-plivo-developers) - [Plivo Browser SDK — Getting Started Tutorial | Plivo](#plivo-browser-sdk-getting-started-tutorial-plivo) - [API Reference for SMS API, Voice API, and more — Docs | Plivo](#api-reference-for-sms-api-voice-api-and-more-docs-plivo) - [Get Started with Lookup API | Plivo Lookup](#get-started-with-lookup-api-plivo-lookup) - [Get started with Plivo PHLO | Plivo Docs](#get-started-with-plivo-phlo-plivo-docs) - [Overview | Plivo Developers](#overview-plivo-developers) - [Number Masking vs Lookup- Get Started with Number Masking API](#number-masking-vs-lookup-get-started-with-number-masking-api) - [Get Started with PHP using PHP Server | Plivo Voice](#get-started-with-php-using-php-server-plivo-voice) - [Get Started with Voice Notifications Using Node.js | Plivo Docs](#get-started-with-voice-notifications-using-node-js-plivo-docs) - [Applications | Plivo Developers](#applications-plivo-developers) - [Get Started with PHP Using Laravel Framework | Plivo Voice](#get-started-with-php-using-laravel-framework-plivo-voice) - [Get started with Voice Alerts using Node.js | Plivo Docs](#get-started-with-voice-alerts-using-node-js-plivo-docs) - [Get Started with Python Using Flask Framework| Plivo Voice](#get-started-with-python-using-flask-framework-plivo-voice) - [Send and validate code | Plivo Developers](#send-and-validate-code-plivo-developers) - [Get started with Voice Survey using PHLO | Plivo Docs](#get-started-with-voice-survey-using-phlo-plivo-docs) - [Get Started with Python Using Django Framework | Plivo Voice](#get-started-with-python-using-django-framework-plivo-voice) - [Reporting | Plivo Developers](#reporting-plivo-developers) - [Get Started with Call Forwarding Using Node.js | Plivo Docs](#get-started-with-call-forwarding-using-node-js-plivo-docs) - [Get Started with Python Using FastAPI Framework| Plivo Voice](#get-started-with-python-using-fastapi-framework-plivo-voice) - [Callbacks | Plivo Developers](#callbacks-plivo-developers) - [Get Started with Conference Calling with a PIN Using Node.js| Plivo Docs](#get-started-with-conference-calling-with-a-pin-using-node-js-plivo-docs) - [Get Started with Python Using Sanic Framework| Plivo Voice](#get-started-with-python-using-sanic-framework-plivo-voice) - [Fraud Control | Plivo Developers](#fraud-control-plivo-developers) - [Get started with Pinless Conference using Node.js| Plivo Docs](#get-started-with-pinless-conference-using-node-js-plivo-docs) - [Get Started with Ruby Using Sinatra Framework | Plivo Voice](#get-started-with-ruby-using-sinatra-framework-plivo-voice) - [Get Started with Ruby on Rails Framework | Plivo Voice](#get-started-with-ruby-on-rails-framework-plivo-voice) - [Translation support | Plivo Developers](#translation-support-plivo-developers) - [Validating Requests and Responses | Plivo Developers](#validating-requests-and-responses-plivo-developers) - [Get Started Sending SMS Notifications Using Node.js | Plivo Docs](#get-started-sending-sms-notifications-using-node-js-plivo-docs) - [Get Started with SMS Surveys Using Node.js | Plivo Docs](#get-started-with-sms-surveys-using-node-js-plivo-docs) - [Get started with Phone System IVR using Node.js| Plivo Docs](#get-started-with-phone-system-ivr-using-node-js-plivo-docs) - [Authentication | Plivo API Reference](#authentication-plivo-api-reference) - [Get Started with .NET Framework | Plivo Voice](#get-started-with-net-framework-plivo-voice) - [API Request | Plivo API Reference](#api-request-plivo-api-reference) - [Get Started with Node.js Using Express | Plivo Voice](#get-started-with-node-js-using-express-plivo-voice) - [Get Started with .NET Core | Plivo Voice](#get-started-with-net-core-plivo-voice) - [Content-Type | Plivo API Reference](#content-type-plivo-api-reference) - [Get started with Voicemail using Node.js| Plivo Docs](#get-started-with-voicemail-using-node-js-plivo-docs) - [Timeouts and Proxies | Plivo API Reference](#timeouts-and-proxies-plivo-api-reference) - [Overview | Plivo API Reference](#overview-plivo-api-reference) - [Overview | Plivo XML Reference](#overview-plivo-xml-reference) - [Get Started with Node.js using Sails Framework | Plivo Voice](#get-started-with-node-js-using-sails-framework-plivo-voice) - [Get Started with Node.js using NestJS Framework | Plivo Voice](#get-started-with-node-js-using-nestjs-framework-plivo-voice) - [Pagination | Plivo API Reference](#pagination-plivo-api-reference) - [Session | Plivo API Reference](#session-plivo-api-reference) - [The Session Object | Plivo API Reference](#the-session-object-plivo-api-reference) - [Node.js Using Serverless Framework | Plivo](#node-js-using-serverless-framework-plivo) - [API Response | Plivo API Reference](#api-response-plivo-api-reference) - [Get Started with Java Using Spring Framework| Plivo Voice](#get-started-with-java-using-spring-framework-plivo-voice) - [Get Started with Go Using Gin Web Framework | Plivo Voice](#get-started-with-go-using-gin-web-framework-plivo-voice) - [Get Started with Java Using Spark Framework| Plivo Voice](#get-started-with-java-using-spark-framework-plivo-voice) - [Get Started with Go | Plivo Voice](#get-started-with-go-plivo-voice) - [Create a session | Plivo API Reference](#create-a-session-plivo-api-reference) - [Retrieve a session | Plivo API Reference](#retrieve-a-session-plivo-api-reference) - [Get Started Using Postman Collections for Plivo Voice APIs](#get-started-using-postman-collections-for-plivo-voice-apis) - [List all sessions | Plivo API Reference](#list-all-sessions-plivo-api-reference) - [Validate a session | Plivo API Reference](#validate-a-session-plivo-api-reference) - [Migrate from Twilio to the Plivo Voice API | Plivo](#migrate-from-twilio-to-the-plivo-voice-api-plivo) - [Voice Overview | Plivo Docs](#voice-overview-plivo-docs) - [Verify Status Callbacks | Plivo API Reference](#verify-status-callbacks-plivo-api-reference) - [Plivo Docs - iOS SDK v2 for VoIP | Plivo](#plivo-docs-ios-sdk-v2-for-voip-plivo) - [Voice Terminology | Plivo Docs](#voice-terminology-plivo-docs) - [Voice Features | Plivo Docs](#voice-features-plivo-docs) - [Android Mobile SDK — Getting Started Tutorial | Plivo](#android-mobile-sdk-getting-started-tutorial-plivo) - [Voice Callbacks | Plivo Docs](#voice-callbacks-plivo-docs) - [Account Limits | Voice API](#account-limits-voice-api) - [Voice STIR/SHAKEN | Plivo Docs](#voice-stir-shaken-plivo-docs) - [Configurable Callback Retries | Plivo Docs](#configurable-callback-retries-plivo-docs) - [Outbound Voice Geo Permissions | Plivo Docs](#outbound-voice-geo-permissions-plivo-docs) - [Plivo SIP Endpoints - Getting Started Tutorial | Plivo](#plivo-sip-endpoints-getting-started-tutorial-plivo) - [IP Address Whitelisting | Plivo Developers](#ip-address-whitelisting-plivo-developers) --- # Quickstart guides, use-case guides and reference documentation for our SMS API, Voice API, and more | Plivo Add SMS text messaging or voice calling functionality to your applications in minutes ===================================================================================== Getting started --------------- [![image description](https://docs.plivo.com/assets/dist/images/v2/icon/ic-sms-colored.svg)\ \ ### Messaging API Platform\ \ Programmatically send and receive text messages globally.\ \ Get Started](/docs/messaging/) [![image description](https://docs.plivo.com/assets/dist/images/v2/header/drop-ic-voice.svg)\ \ ### Voice API Platform\ \ Make and receive phone calls and add powerful functionality to your voice calls.\ \ Get Started](/docs/voice/) [![image description](https://docs.plivo.com/assets/dist/images/v2/header/verify-api-ic.svg)\ \ ### Verify API\ \ Verify users globally with a multi-channel 2FA solution.\ \ Get Started](/docs/verify/api/overview/) How-to guides ------------- [![image description](https://docs.plivo.com/assets/posts/images/use-cases/voice-notification.svg)\ \ ### Voice Notification\ \ Send audio notifications using voice calls.\ \ Learn More](/docs/voice/use-cases/voice-notification/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/voice-alert.svg)\ \ ### Voice Alerts\ \ Alert users immediately using a voice call.\ \ Learn More](/docs/voice/use-cases/voice-alerts/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/voice-survey.svg)\ \ ### Voice Survey\ \ Conduct surveys over a voice call.\ \ Learn More](/docs/voice/use-cases/voice-survey/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/call-forwarding.svg)\ \ ### Call Forwarding\ \ Redirect incoming calls to another phone number.\ \ Learn More](/docs/voice/use-cases/call-forwarding/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/conference.svg)\ \ ### Conference with PIN\ \ Connect multiple people in a secure voice call.\ \ Learn More](/docs/voice/use-cases/conference-with-pin/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/conference.svg)\ \ ### Pinless Conference\ \ Connect multiple people over a single voice call.\ \ Learn More](/docs/voice/use-cases/call-conference/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/sms-notification.svg)\ \ ### SMS Notification\ \ Notify users with regular updates using SMS.\ \ Learn More](/docs/messaging/use-cases/sms-notification/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/2-way-sms.svg)\ \ ### SMS Survey\ \ Send and receive SMS texts to conduct surveys.\ \ Learn More](/docs/messaging/use-cases/sms-survey/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/ivr.svg)\ \ ### Phone System IVR\ \ Deliver focused services based on customer inputs.\ \ Learn More](/docs/voice/use-cases/ivr/node/) [![image description](https://docs.plivo.com/assets/posts/images/use-cases/voicemail.svg)\ \ ### Voicemail\ \ Record important customer information while you’re away.\ \ Learn More](/docs/voice/use-cases/voicemail/node/) Reference guides ---------------- [![image description](https://docs.plivo.com/assets/new_docs/images/ic-phlo.svg)\ \ ### PHLO Reference\ \ Drag, drop, and deploy to create voice calls and SMS messages in minutes.\ \ Get Started](/docs/phlo/) [![image description](https://docs.plivo.com/assets/new_docs/images/ic-api-reference.svg)\ \ ### API Reference\ \ Build voice call and SMS applications in any web standard language.\ \ Get Started](/docs/voice/api/overview/) [![image description](https://docs.plivo.com/assets/new_docs/images/ic-xml-reference.svg)\ \ ### XML Reference\ \ Synchronously control a call or a message.\ \ Get Started](/docs/voice/xml/overview/) More resources -------------- [![image description](https://docs.plivo.com/assets/new_docs/images/ic-sdk.svg)\ \ ### Client SDKs\ \ Embed VoIP in your web or mobile app.\ \ Get Started](/docs/sdk/client/browser/overview/) [![image description](https://docs.plivo.com/assets/new_docs/images/ic-integration.svg)\ \ ### Integrations\ \ Out-of-the-box integrations with Plivo\ \ Get Started](/docs/integrations/) [![image description](https://docs.plivo.com/assets/new_docs/images/ic-faq.svg)\ \ ### Support\ \ Find answers to all your questions.\ \ Get Started](https://support.plivo.com/hc/en-us/) --- # Get Started with PHP using PHP Server | Plivo Voice * [PHP Server](/docs/voice/quickstart/php/) * [PHP Laravel](/docs/voice/quickstart/php-laravel/) Get Started with PHP Using PHP Server ===================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your PHP dev environment ------------------------------- You must set up and install PHP and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) or [Windows](https://www.php.net/manual/en/install.windows.php) or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install the Plivo PHP SDK * Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp * To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php * Alternatively, download this [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(["from" => "", "to" => ""]); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ php TriggerPhlo.php Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both PHLO and API/XML on our documentation pages. Install PHP and the Plivo PHP SDK --------------------------------- You must set up and install PHP and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) , [Windows](https://www.php.net/manual/en/install.windows.php) , or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install the Plivo PHP SDK Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a PHP server to handle outbound calls Create a file called `MakeCall.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 "; $auth_token = ""; $client = new RestClient($auth_id, $auth_token); $response = $client->calls->create('', [''], 'https://s3.amazonaws.com/static.plivo.com/answer.xml',); print_r($response); **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use $\_ENV or putenv/getenv to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. $ php MakeCall.php Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a PHP server to handle incoming calls Create a file called `receive_call.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 addSpeak($speak_body); Header('Content-type: text/xml'); echo($response->toXML()); ?> Save the the file and start the server. $ php -S localhost:8000 You should see your basic server application in action at http://localhost:8000/receive\_call.php. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_phpapp.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a PHP server to forward calls Create a file called `forward_call.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 "https://.com/dial_status/", 'method' => "POST", 'redirect' => "true" ); $dial = $response->addDial($params); $number = ""; $dial->addNumber($number); Header('Content-type: text/xml'); echo($response->toXML()); Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-php-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the PHP application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Overview | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) Overview ======== The Plivo API uses HTTP verbs and standard HTTP status codes to make it easier for you to integrate communications into your code. To secure your requests to our servers, we serve our API over HTTPS. If you’re looking for our client SDKs, you can find them at [iOS SDK](https://www.plivo.com/docs/sdk/client/ios/overview/) , [Android SDK](https://www.plivo.com/docs/sdk/client/android/overview/) , and [Browser SDK](https://www.plivo.com/docs/sdk/client/browser/overview/) . **Note:** The current version of the API is **v1**, and the server SDKs are versioned as **latest** and **legacy**. #### **API Endpoint** `POST` `https://api.plivo.com/{version}/` Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with PHP Server | Plivo SMS * [PHP Server](/docs/messaging/quickstart/php-server/) * [PHP Laravel](/docs/messaging/quickstart/php-laravel/) Get Started with PHP Using PHP Server ===================================== Sign up for a Plivo account --------------------------- When you [sign up with Plivo](https://console.plivo.com/accounts/register/) , we give you a free trial account and free credits to experiment with and learn about our services. You can [add a number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS service features. Follow these steps to get a free trial account: 1. [Sign up](https://console.plivo.com/accounts/register/) with your work email address. 2. Check your inbox for an activation email message from Plivo. Click on the link in the message to activate your account. 3. Enter your mobile number to complete the phone verification step. ### Sign up with your work email address ![Sign up with email address](https://docs.plivo.com/assets/posts/images/sms/quickstart/signup.jpg) If you have any issues creating a Plivo account, please contact our [support team](https://support.plivo.com/hc/en-us/) for assistance. To get started, try sending an SMS message either by using our API and XML documents, or via [PHLO](https://www.plivo.com/docs/phlo/) , our visual design tool, which allows you to create message flows using an intuitive canvas and deploy them with few clicks. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_api.svg)Using API](#api) * * * ## Set up your PHP dev environment You must set up and install PHP and Plivo’s PHP SDK before you send your first message. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) or [Windows](https://www.php.net/manual/en/install.windows.php) or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V #### Install the Plivo PHP SDK * Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp * To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php * Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install Once you’ve set up your development environment, you can start sending and receiving messages using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Send your first outbound SMS/MMS message ---------------------------------------- You can create and deploy a PHLO to send your first outbound SMS message with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO * [SMS](#osx) * [MMS](#linux) ![Create PHLO for outbound SMS](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms.gif) ![Create PHLO for outbound MMS](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_mms.gif) To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming, or API request. * From the list of components on the left-hand side, drag and drop the **Send Message** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Send Message** node. * In the Configuration pane at the right of the canvas, configure the **Send Message** node with a sender ID in the **From** field. Enter the destination number you wish to send a message to in the **To** field. Put your message in the **Text** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * If you’d like to send an MMS message, configure the **Media URLs** field with the media files you’d like to send. * Once you’ve configured the node, click **Validate** to save the configuration. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Edit app/http/controllers/phloController.php and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit app/http/controllers/phloController.php and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(["From" => "", "To" => ""]); // These are the fields entered in the PHLO console print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run your code. $ php TriggerPhlo.php Receive your first inbound SMS/MMS message ------------------------------------------ You can create and deploy a PHLO to receive an inbound text message with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming text messages, you must have an SMS-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO * [SMS](#osx) * [MMS](#linux) ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/receive_sms.gif) ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/receive_mms.gif) To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left-hand side, drag and drop the **HTTP Request** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Message** trigger state to the **HTTP Request** node. * In the Configuration pane at the right of the canvas, configure the **HTTP Request** node. Specify the address of your web server and specify that from , to , and text fields should be passed along with the request. * Once you’ve configured the node, click **Validate** to save the configuration. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/config_receieve_sms_mask.png) ### Test You can now send a text message to your Plivo phone number and see how the inbound text is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an incoming SMS/MMS message ----------------------------------- You can create and deploy a workflow to implement text message forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming text messages, you must have an SMS-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO * [SMS](#osx) * [MMS](#linux) ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/forward_sms.gif) ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/forward_mms.gif) To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left-hand side, drag and drop the **Send Message** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Message** trigger state to the **Send Message** node. * In the Configuration pane at the right of the canvas, configure the **Send Message** node with the phone number to which you want to forward the message. * Once you’ve configured the node, click **Validate** to save the configuration. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/config_forward_sms_mask.png) ### Test You can now send a text message to your Plivo phone number and see how the inbound text is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than a dozen use cases](/docs/messaging/use-cases/send-an-sms/php/) with code for both PHLO and API/XML on our documentation pages. Install PHP and the Plivo PHP SDK --------------------------------- You must set up and install PHP and Plivo’s PHP SDK before you send your first SMS message. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) , [Windows](https://www.php.net/manual/en/install.windows.php) , or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install the Plivo PHP SDK Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. [Buy Numbers](https://console.plivo.com/phone-numbers/search/) on the Plivo console or via the [Numbers API](https://www.plivo.com/docs/numbers/api/phone-number/#buy-a-phone-number) . ### Set up a PHP server Create a file called `SendMessage.php` and paste into it this code. * [SMS](#server-sms) * [MMS](#server-mms) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ",""); $message_created = $client->messages->create( [ \ "src" => "",\ "dst" => "",\ "text" =>"Hello, from PHP Server!",\ ] ); print_r($response); ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 ",""); $client->client->setTimeout(40); $mediaURLs = ['https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif']; $mediaIDs = ['801c2056-33ab-499c-80ef-58b574a462a2']; $response = $client->messages->create( [ \ "src" => "",\ "dst" => "",\ "text" =>"Hello, MMS from PHP Server!",\ "type" => "mms", \ "media_urls" => $mediaURLs, \ "media_ids" => $mediaIDs\ ] ); print_r($response); ?> Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). In countries other than the US and Canada you can use a [sender ID](/docs/messaging/concepts/sender-id-usage/) for the message source. **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use $\_ENV or putenv/getenv to store environment variables and fetch them when initializing the client. ### Test Save the file and run it. $ php SendMessage.php Receive your first inbound SMS/MMS message ------------------------------------------ To receive incoming messages, you must have a Plivo phone number that supports SMS; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . ### Set up a PHP server Create a file called `receive_sms.php` and paste into it this code. * [SMS](#receive-server-sms) * [MMS](#receive-server-mms) 1 2 3 4 5 6 7 8 [Applications](https://console.plivo.com/sms/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive SMS`. Enter the server URL you want to use (for example `https://.com/receive_sms/`) in the `Message URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/sms/quickstart/create_SMS_app.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive SMS` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive SMS App](https://docs.plivo.com/assets/posts/images/sms/quickstart/assign_SMS_app.jpg) ### Test Send a text message to the Plivo number you specified using any phone. Reply to an incoming SMS/MMS message ------------------------------------ To receive incoming messages, you must have a Plivo phone number that supports SMS; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . ### Set up a PHP server Create a file called `reply_to_sms.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 $to_number, 'dst' => $from_number ); $message_body = "This is an automatic response"; $response->addMessage($message_body, $params); return $response->toXML(); } header("Content-type: text/xml; charset=utf-8"); echo sendResponseWithPlivo(); If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-php-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to reply to messages Associate the controller you created with Plivo by creating a Plivo application. Visiting Messaging > [Applications](https://console.plivo.com/sms/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Reply Incoming SMS`. Enter the server URL you want to use (for example `http://.com/replysms/`) in the `Message URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/sms/quickstart/create_reply_sms.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Reply Incoming SMS` (the name we gave the application). Click **Update Number** to save. ### Test Send a text message to the Plivo number you specified using any phone. You should receive a reply. More use cases -------------- We illustrate [more than a dozen use cases](/docs/messaging/use-cases/send-an-sms/php/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Zentrunk Quickstart Guide | Plivo ![Zentrunk Hero](https://docs.plivo.com/assets/posts/images/trunking/zentrunk-hero.png) Overview -------- Zentrunk, Plivo’s SIP trunking service, provides global coverage for your outbound and inbound voice calls, working with your current cloud or on-premises communications infrastructure. Whether you’re looking to increase the capacity of your current telecom stack, increase coverage and phone number inventory, or extend your on-premises infrastructure to the cloud, Zentrunk can get you started. No minimum spends, carrier negotiations, or long-term contracts are required, and you can provision SIP trunks instantly using our console. Why Zentrunk? ------------- Zentrunk provides benefits such as: **Scalability**: Zentrunk supports your organization’s growth across multiple geographic locations. By combining voice and data in a single network, SIP trunking lets your organization quickly open new sites or establish full-time remote workers. You can scale as you grow by self-provisioning local, international, mobile, and toll-free numbers in more than 70 countries, configuring them in your trunk, and terminating calls from your IP PBX. You can also make calls to more than 190 countries using Zentrunk to make your business more globally accessible. **Cost savings**: With traditional phone service, your organization is subject to different, often variable charges for your local, long distance, and international calling. Moving from traditional telecom systems to SIP trunking helps you save on recurring costs, as you can build your entire telecom system in the cloud, and be billed on a simple per-usage basis. You can also save by forgoing the physical infrastructure and hardware investments that typically come with scaling phone lines. With Zentrunk, adding phone lines or services is as simple as purchasing an additional handset and scaling your monthly service agreement. **Reliability**: Traditional phone systems are prone to interruptions from factors such as weather events and networking issues. SIP trunking is more reliable, since you can add failover routing if a primary IP address is not responsive. With a redundant infrastructure across multiple geographies and at least three local carrier connections across countries, Zentrunk promises 99.99% uptime. **Easy management for your IT teams:** Your IT team will never have to wait on hold to speak to a customer service representative again. SIP trunking and VoIP phones offer easy-to-use administrative portals for on-site management, including actions like adjusting call routing, changing extensions, and adding phone lines on demand. Plivo’s 24x7 premium support and consultative customer success team can provide you with technical guidance when you need it. Getting started --------------- ### Plivo account You need a Plivo account to start using Zentrunk. You can get a free trial account to experiment with and learn about our services. 1. [Sign up](https://console.plivo.com/accounts/register/) through our console with your work email address 2. Check your inbox for an activation email message from Plivo. Click on the link in the message to activate your account. 3. Enter your mobile number to complete the phone verification step. If you have any questions about creating a Plivo account, reach out to our [support team](https://support.plivo.com/hc/en-us) for assistance. ### Supported software and hardware Zentrunk is compatible with a broad range of software and devices. We support: * [All major IP PBXes](/docs/sip-trunking/interconnection-guides/overview/) * All SIP-based hardphones and softphones * Integrations with all WebRTC clients and endpoints ### Supported SIP methods Zentrunk supports these SIP methods: ACK, BYE, CANCEL, INVITE, OPTIONS, and UPDATE. We don’t support INFO, MESSAGE, NOTIFY, PRACK, PUBLISH, REFER, REGISTER, or SUBSCRIBE. ### Supported codecs Zentrunk supports G.711 U-law (PCMU) and A-law (PCMA) codecs. ### Signaling IP addresses You may need to whitelist Plivo IP addresses in your firewall to ensure that calls get routed without interruption. Please whitelist all of these IP addresses, as calls might get routed through a different region in the event of a service disruption in a specific region. | **Regions** | **IP Addresses** | **Signaling Ports** | **Media Ports** | | --- | --- | --- | --- | | North California, USA | 13.52.9.0/25
216.120.187.128/26 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | | Virginia, USA | 18.214.109.128/25
18.215.142.0/26
204.89.148.128/26 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | | Frankfurt, Germany | 3.120.121.128/26 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | | São Paulo, Brazil | 18.228.70.64/26
54.233.191.0/27 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | | Sydney, Australia | 13.238.202.192/26 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | | Singapore | 18.136.1.128/26
204.89.149.128/27 | 5060 (UDP/TCP)
5061 (TLS) | 10000 - 30000 (UDP/TCP) | ### Internet bandwidth SIP trunk calls over the internet require sufficient bandwidth to support peak concurrent call traffic. Plivo needs about 100Kbps for every successful call, so your peak bandwidth requirements can be calculated as 100Kbps \* peak concurrent calls. ### Calls-per-second limitations #### Outbound limitations The calls-per-second limitation for Zentrunk SIP trunking is based on both account-level CPS and trunk-level CPS. The account-level CPS is the rate at which calls may be made from an account in a second, while the trunk-level CPS applies to each of the trunks individually in the account. Businesses can choose different ways to allocate their account-level CPS across trunks in their account. **Scenario 1**: A user has 25 account-level CPS and three trunks * 2 trunks are set at 10 CPS (high-volume use cases) * 1 trunk is set at 5 CPS (low-volume use case) **Scenario 2**: A user has 10 account-level CPS and 10 trunks * Each trunk has a CPS of 10 * This allows for a “free-for-all” where if one trunk is consistently initiating calls at a rate of 10 CPS, calls from other trunks would fail **Note:** You cannot exceed the account CPS limit even if you have multiple trunks in your account. If it exceeds, then calls will fail with the error “cps\_limit\_reached” and error code 5180. By default, the calls-per-second rate for Zentrunk is set to 2 CPS per account and 1 CPS per trunk. If you have higher CPS requirements, please contact our [sales team](https://www.plivo.com/contact/sales/) . For help with technical issues related to Zentrunk, please submit a ticket with the [Plivo support team](https://support.plivo.com/hc/en-us/requests/new?ticket_form_id=360000156292) . #### Inbound limitations There are no calls-per-second constraints for inbound trunks in Zentrunk SIP trunking. Outbound trunks (termination) ----------------------------- ![Outbound SIP Trunking](https://docs.plivo.com/assets/dist/img/sip-trunking/getting-started/outbound-sip-trunking.png) Zentrunk’s outbound SIP trunks let you reach fixed and mobile phones in more than 190 countries. There are no restrictions or limitations on channels or ports. Each trunk comes with unlimited concurrent call capability. You get all of the standard features of a telco (such as dynamic CLI, DTMF support, and per-second billing) and more (including secure trunking, fraud detection, and instant provisioning). You pay only for what you use, with no long-term contracts. ### Create an outbound trunk To use Zentrunk to terminate calls, you need to set up trunk authentication on the Plivo console. Authenticating your trunk ensures that Zentrunk accepts only traffic that your infrastructure sends securely. You can configure your trunk to be authenticated by an IP access control list, a credentials list, or both. ![Outbound SIP Trunking](https://docs.plivo.com/assets/posts/images/trunking/outbound-trunk.gif) #### To create an outbound trunk: 1. In the Plivo console, visit Zentrunk > [Outbound Trunks](https://console.plivo.com/zentrunk/trunks/) and click **Create New Outbound Trunk**. 2. Under Trunk Details, enter a name for your trunk (for example, Plivo Test). **Note:** By default, the trunk is enabled. 3. Under Trunk Authentication, select the IP Access Control List, the Credentials List, or both. **Note:** Make sure to choose either an IP Access Control List or a Credentials List. The IP Access Control List consists of a list of the IP addresses from which a SIP Invite will be accepted for this trunk. The Credentials List provides a username and password that will be used to authenticate a SIP Invite. **To create an IP Access Control List:** 1. To add a new IP Access Control List, click **\+ Add New IP ACL**. 2. In the Create New IP Access Control List window, enter the name for your IP Access Control List (for example, TestACL) and then enter the IP addresses to be whitelisted in the IP Address List field. **Note:** You can add multiple comma-separated IP addresses. 3. Click **Create ACL** to save and add your IP Access Control List. **To create a Credentials List:** 1. To add a new Credentials List, click **\+ Add New Credentials List**. 2. In the Create Credentials List window, enter a name for your Auth Group (for example, TestCredList), a username, and a password. 3. Click **Create Credentials List** to save and add your Credentials List. Select an IP Group, Auth Group, or both. Under Secure Trunking, use the Disabled/Enabled toggle button to enable secure trunking. **Note:** By default, secure trunking is disabled, but we strongly recommend you enable it, as we discuss in the next section. 4. Click **Create Trunk** to create your outbound trunk. Secure trunking on outbound trunks ---------------------------------- To ensure that the information shared between your communication infrastructure and Zentrunk is secure, we recommend using the Secure Trunking feature. You can secure your trunk by encrypting and authenticating the signaling and media data packets involved for a SIP call over the internet. ### Encrypt signaling packets You can encrypt signaling by using TLS (Transport Layer Security) protocol. Communication over TLS ensures authentication between two transport endpoints over an unsecured path for the SIP messages. We support TLS versions 1.2 and 1.3. * **If Secure Trunking is enabled**: Zentrunk will communicate with your PBX or SBC over **TLS** for **Signaling**. * **If Secure Trunking is disabled**: The calls will be over **TCP/UDP** for **Signaling**. ### Encrypt media packets Zentrunk uses Secure Real-Time Protocol (SRTP) to secure RTP (media) packets. * **If Secure Trunking is enabled**: Zentrunk will communicate with your PBX or SBC over **SRTP** for **Media**. * **If Secure Trunking is disabled**: The calls will be over **RTP** for **Media**. **Note:** You can use SRTP regardless of the SIP signaling messages being on TCP/UDP. However, Plivo strongly recommends you enable a secure mode of communication between your infrastructure and Zentrunk. Inbound trunks (origination) ---------------------------- ![Inbound SIP Trunking](https://docs.plivo.com/assets/dist/img/sip-trunking/getting-started/inbound-phone-number.png) With Zentrunk, you can instantly access the inbound phone number DIDs in Plivo’s inventory of more than 5 million phone numbers representing more than 60 countries. Each phone number comes with unlimited concurrent call capacity. Zentrunk customers can also instantly search, filter, and provision fixed, mobile, toll-free, and SMS-enabled phone numbers through the Zentrunk API or user interface. Also, our carrier team can help you to port your phone numbers to Zentrunk from your current provider. ### Create an inbound trunk ![Inbound SIP Trunking](https://docs.plivo.com/assets/posts/images/trunking/inbound-trunk.gif) To create an inbound trunk: 1. In the Plivo console, visit Zentrunk > [Inbound Trunks](https://console.plivo.com/zentrunk/inbound-trunks/) and click **Create New Inbound Trunk**. 2. Under Trunk Details, enter a name for your trunk (for example, Plivo Inbound). **Note:** The Enabled checkbox is selected by default. 3. Under Trunk Authentication, select the Primary URI and Fallback URI of your PBX. **Note:** The Primary URI is the FQDN or IP address to which all calls are forwarded first. If the Primary URI is unresponsive, calls will be forwarded to the Fallback URI. To add a new Primary or Fallback URI, click **Add New URI**. On the Create URI window, enter a name for your URI (for example, inbounduri), and then enter the URI (the FQDN or IP address of your VoIP infrastructure). To enable Authentication, click on the **Authentication** option and provide your username and password. Click **Create URI** to save and add your URI. 4. Once you’ve created and selected your Primary and Fallback URI, click **Create Trunk**. Your inbound trunk will be created. ### Assigning an inbound trunk to a phone number The next task is to link your trunk with phone numbers. You can link the trunk with existing phone numbers in your account or buy a new phone number to use. 1. If you wish to use existing numbers, select the phone numbers under the **Current Phone Numbers** section, and click **Link Selected Numbers**. 2. If you wish to use a new number, navigate to the **Buy New Number** section and choose the country, prefix, type, capability, and click on **Search**. 3. Select a phone number and click **Buy Number**. The number will be added to your account and linked with your inbound trunk. To learn more about buying a Plivo phone number, visit our [Buy a Phone Number Quickstart Guide](/docs/numbers/guides/buy-a-number/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Numbers | Plivo Developers Overview -------- This guide covers all the types of numbers Plivo offers. You can learn more about searching and buying numbers in the [Plivo PhoneNumbers API documentation](/docs/numbers/api/phone-number/) , and learn more about accessing the numbers already added to your account in the [Plivo Numbers API documentation](/docs/numbers/api/account-phone-number/) . Understanding phone number types -------------------------------- Plivo offers phone numbers of three types: fixed, toll-free, and mobile. The phone number type can generally be identified using a phone number’s [prefix](https://en.wikipedia.org/wiki/List_of_mobile_telephone_prefixes_by_country) , which it typically indicates the capability (receive call and/or SMS) and the region the phone number belongs to. (Phone number prefixes in the US and Canada don’t indicate type and capability, however.) Evaluating phone number types ----------------------------- What type of phone number should you use? Consider: * Your use case * The cost you expect the dialer to incur * The expectation you want to set for the user you communicate with Here are more details about fixed, toll-free, and mobile phone numbers, along with some discussion on the circumstances in which they should be used. Fixed numbers ------------- Fixed numbers are assigned to a specific region, which could be a city, an area, or a country. For instance, phone numbers in the format +1 (212) nnn-nnnn correspond to the Manhattan area in New York City, while +1 (917) nnn-nnnn numbers correspond to anywhere in New York City. Similarly, phone numbers in the format +33 5 nn nn nn nn correspond to the southwest France region and +33 9 nn nn nn nn correspond to the entire country of France. Fixed numbers generally support receiving calls. In a few countries, such as the US and Canada, they may support SMS as well. Users dialing from within the phone number’s region are charged local rates. Individuals and local businesses that communicate with customers in a specific city or an area typically use fixed numbers that belong to the area. Larger businesses that engage with customers across a whole country should use fixed numbers with prefixes that are reserved for the entire country. Toll-free numbers ----------------- Toll-free numbers, also called freephone numbers, are phone numbers that are billed to the called party for all incoming calls and are free of charge for the calling party. Most countries reserve a set of dialing [prefixes](https://en.wikipedia.org/wiki/Toll-free_telephone_number#Around_the_world) , typically 1800 or 800, to denote toll-free services. Toll-free numbers are generally used by businesses that want their customers to reach them at no cost. Businesses also use toll-free numbers to send transactional and promotional SMS messages to opted-in customers. Mobile numbers -------------- Mobile numbers are similar to the phone numbers connected to SIM cards used in cell phones. However, they can be used like fixed or toll-free numbers, and are not connected to any SIM card. Most countries assign a range of prefixes for mobile numbers, which lets these phone numbers be distinguished from other types of numbers. For instance, the prefixes +33 6 and +33 7 in France and +45 91 through +45 93 in Denmark are reserved for mobile numbers. Mobile numbers generally support sending and receiving SMS messages, and in some countries also support making and receiving calls. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Overview | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) Overview ======== All Plivo APIs use HTTP verbs and standard HTTP status codes to make it easy for you to integrate communications into your code. To secure requests to our servers, we serve our APIs over HTTPS. You can find documentation on our client SDKs on these pages: [iOS SDK](/docs/sdk/client/ios/overview/) , [Android SDK](/docs/sdk/client/android/overview/) , and [Browser SDK](/docs/sdk/client/browser/overview/) . **Note**: The current version of the APIs is `v1`, and the server SDKs are versioned as `latest` and `legacy`. #### API Endpoint `POST` `https://api.plivo.com/{version}/` Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Integrations | Plivo Developers Integrations with Plivo ======================= Here are some creative ways you can add voice and SMS capabilities to your applications. * How to create a Plivo Zap in [Zapier](/docs/integrations/zapier/) * How to use the Plivo connector in [Microsoft Power Automate](/docs/integrations/microsoft-power-automate/) to create SMS and voice applications * How to create Plivo SMS and voice apps using [Integromat](/docs/integrations/integromat/getting-started/) * How to enable MFA on [Auth0](/docs/integrations/auth0/) using Plivo * How to create a workflow on [n8n.io](/docs/integrations/n8n/) using Plivo * How to create a workflow on [Pipedream](/docs/integrations/pipedream/) using Plivo * How to create an automation in a couple of clicks on [Integrately](/docs/integrations/integrately/) using Plivo * How to send SMS from [Github Actions](/docs/integrations/github-actions-sms/) using Plivo * How to create a workflow on [Tray](/docs/integrations/tray/) using Plivo * How to send SMS and make calls on [EngageBay](/docs/integrations/engagebay/) using Plivo Don't see an integration you need? [Let us know about it](https://support.plivo.com/hc/en-us/) and we can build one. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Plivo Browser SDK — Getting Started Tutorial | Plivo Plivo Browser SDK ================= Introduction ------------ The Plivo Browser SDK lets you make and receive calls using Plivo applications directly from any web browser. Using our SDK, you can create applications such as: 1. **Call Center** — Build efficient call center workflow by allowing your agents to make and receive calls via their browsers. Control call flow in your app using our API. 2. **Click to Call** — When adding click to call for your CRM app, Plivo runs seamlessly in the background to allow your users to interact via audio communication. 3. **Web-Based Help Desk** — Create great service experiences and workflows. Sales and support agents can access customer info while making calls directly from their web browsers. 4. **Web Conferencing** — Build rich conference experiences with Plivo’s out-of-the-box features, including unique call flows, recording calls, and branded conference greetings. How does it work? ----------------- ![plivo Browser SDK for voice SIP calls](https://docs.plivo.com/assets/posts/images/getting-started/calls/browser_sdk.svg) 1. From a browser, a Plivo endpoint initiates an internet call to Plivo’s voice platform. 2. The platform notifies your application server about the call. 3. Plivo handles the call based on XML documents returned by the application server. In this case, a Dial XML element connects the call with the phone number specified in the XML document. 4. Plivo initiates a call to the phone number specified in the Dial XML element. 5. Once the call is answered, the two parties are connected and can talk to each other. To learn more about managing the call flows and types of call flows, refer to our [Voice Overview guide](/docs/voice/concepts/overview/) . Next steps ---------- Now that you know the fundamentals, you can build a simple app. Get inspiration from our [sample applications](https://github.com/plivo/plivo-browser-sdk2-examples/) and learn implementation details from our [Browser SDK Reference documentation](/docs/sdk/client/browser/reference/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # API Reference for SMS API, Voice API, and more — Docs | Plivo Complete API reference for the Plivo APIs, XML, and PHLO ======================================================== Full API Reference ------------------ ![SMS API](https://docs.plivo.com/assets/dist/images/v2/icon/ic-sms-colored.svg) ### Messaging API Use familiar languages to easily integrate SMS functionality and enable your applications to send and receive text messages globally. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate SMS APIs into your application.](/docs/messaging/api/overview/) #### XML Reference [### Introduction\ \ Use Plivo’s XML to design your SMS workflows.](/docs/messaging/xml/overview/) [### Message\ \ Use a simple REST interface to send and receive SMS messages globally.](/docs/messaging/api/message/) [### Message Element\ \ Use the Message element to reply to an incoming SMS or to forward an SMS.](/docs/messaging/api/overview/) [View All](/docs/messaging/api/overview/) [View All](/docs/messaging/xml/overview/) ![Verify API](https://docs.plivo.com/assets/dist/images/v2/header/verify-api-ic.svg) ### Verify API Use familiar languages to easily integrate SMS and voice functionality and enable your applications to send one-time passwords (OTP) globally. #### API Reference [### Introduction\ \ Programmatically authenticate users via 2FA using SMS and voice calls.](/docs/verify/api/overview/) [### Verify\ \ Use a simple REST interface to send one-time passwords (OTP) globally.](/docs/verify/api/overview/) [View All](/docs/verify/api/overview/) ![Phone Numbers](https://docs.plivo.com/assets/dist/images/v2/header/drop-ic-phone-numbers.svg) ### Phone Numbers Search for and purchase local and toll-free phone numbers for your business from our inventory of millions of global numbers. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate phone number API calls into your applications.](/docs/numbers/api/overview/) [### Account Phone Number\ \ Update, modify, and delete your Plivo rented number or BYOC number.](/docs/numbers/api/account-phone-number/) [### Phone Number\ \ Use the Phone Numbers object to search for and buy a Plivo phone number.](/docs/numbers/api/phone-number/) [View All](/docs/numbers/api/overview/) ![PHLO Reference](https://docs.plivo.com/assets/dist/images/v2/icon/ic-phlo-colored.svg) ### PHLO Reference Access prebuilt use case templates with a drag-and-drop interface that helps you think, build, and deploy within minutes. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate dedicated PHLO APIs.](/docs/phlo/api/overview/) [### PHLO\ \ Use HTTP and standard HTTP status codes to manage callers on PHLO — mute, hold, hang up, transfer, and more.](/docs/phlo/api/phlo/) [View All](/docs/phlo/api/overview/) ![Voice API](https://docs.plivo.com/assets/dist/images/v2/icon/ic-voice-colored.svg) ### Voice API Use familiar languages to easily integrate voice functionality into your applications — make, receive, and monitor calls around the world. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate Voice APIs into your applications.](/docs/voice/api/overview/) #### XML Reference [### Introduction\ \ Use XML to control voice and message actions during a call.](/docs/voice/xml/overview/) [### Call\ \ Use the Call object to interact with ongoing calls and retrieve call details.](/docs/voice/api/call/) [### Conference\ \ Use the Conference element to start and join a conference.](/docs/voice/xml/conference/) [View All](/docs/voice/api/overview/) [View All](/docs/voice/xml/overview/) ![Account API](https://docs.plivo.com/assets/dist/images/v2/header/drop-ic-account-api.svg) ### Account API Perform actions to modify and update anything related to your account, such as account details, applications, and end-point specifications. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate Account APIs into your applications.](/docs/account-api/) [### Account\ \ Use the Account object to modify your account details.](/docs/account/api/account/) [### Application\ \ Use answer, hang-up, and message URLs to control incoming calls and SMS messages.](/docs/account-api/api-reference/application/) [View All](/docs/account-api/) ![Lookup API](https://docs.plivo.com/assets/dist/images/v2/header/ic_lookup_api.svg) ### Lookup API Format phone numbers and retrieve additional information to increase lead conversion for your business. #### API Reference [### Introduction\ \ Find out how to authenticate and integrate Lookup API into your applications.](/docs/lookup/api/overview/) [### Lookup API\ \ Use a simple REST interface to determine carrier, number type, format, and country for any phone number worldwide programmatically.](/docs/lookup/api/lookup-phone-number/) [View All](/docs/lookup/) --- # Get Started with Lookup API | Plivo Lookup Get Started with Lookup API =========================== Overview -------- Lookup API helps you format phone numbers and retrieve additional information before sending SMS and MMS messages or making voice calls. Unformatted numbers may be invalid, which can cause calls and messages to fail. With Lookup, you can identify local number formats and reduce the likelihood of undelivered messages. Here’s how to get started with the Lookup API. Sign up for a Plivo account --------------------------- If you’re not already a Plivo customer, you can [sign up for a free trial account](https://console.plivo.com/accounts/register/) to experiment with and learn about our services. Be sure to sign up with your work email address and not one from a generic email provider. Each trial account comes with free credits. You can [add more credits and buy a phone number](https://console.plivo.com/phone-numbers/search/) to test the full range of our voice and SMS service features. If you have any issues creating a Plivo account, please reach out to our [support team](https://support.plivo.com/hc/en-us/) for help. Once you have an account, read about our [server SDKs](/docs/sdk/server/php-sdk/) and install the one for the programming language you want to use. Looking up a number ------------------- Lookup API enables you to identify phone number types (mobile, fixed, VoIP, and toll-free) and the service provider of the phone number, including ported numbers in the US and Canada. Code ---- * [Python](#lookup-api-python) * [Ruby](#lookup-api-ruby) * [Node.js](#lookup-api-node) * [PHP](#lookup-api-php) * [Java](#lookup-api-java) * [Go](#lookup-api-go) * [.NET](#lookup-api-net) * [Curl](#lookup-api-curl) 1 2 3 4 5 6 7 8 import plivo client = plivo.RestClient('','') #Number lookup API response = client.lookup.get("") print(response) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 require 'rubygems' require 'plivo' include Plivo include Plivo::Exceptions api = RestClient.new("","") # Numberlookup API begin response = api.lookup.get('your_number') puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 7 8 9 10 11 let plivo = require('plivo'); let client = new plivo.Client('', ''); // Numberlookup client.lookup.get("") .then(function(response) { console.log(response); }).catch(function(error) { console.log(error); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 ", ""); $client->client->setTimeout(40); // Numberlookup API Product try { $response = $client->lookup->get(""); print_r($response); } catch (PlivoRestException $ex) { print_r(ex); } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 package test; import java.io.IOException; import com.plivo.api.exceptions.PlivoRestException; public class Test { public static void main(String[] args) { Plivo.init("", ""); //Number Lookup API try { System.out.println(com.plivo.api.models.lookup.Number .getter("") .get()); } catch (IOException e) { e.printStackTrace(); } catch (PlivoRestException e) { e.printStackTrace(); } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 package main import ( "fmt" plivo "github.com/plivo/plivo-go/v7" ) func main() { client, err := plivo.NewClient("", "", &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } // Numberlookup response, err := client.Lookup.Get("", plivo.LookupParams{}) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 using System; using System.Collections.Generic; using Plivo; using Plivo.Exception; namespace test_apps { class Program { static void Main(string[] args) { var api = new PlivoApi("",""); // Number Look Up API try { var response = api.Lookup.Get(""); Console.WriteLine(response); } catch (PlivoRestException e) { Console.WriteLine("Exception: " + e.Message); } } } } 1 2 curl -i --user auth_id:auth_token \ https://lookup.plivo.com/v1/Number/{PhoneNumber}?type=carrier Sample Response --------------- ### Success { "api_id": "e4a25a0a-a19f-4ff6-b8b5-1841bea253f6", "phone_number": "+16172252821", "country": { "name": "United States", "iso2": "US", "iso3": "USA" }, "format": { "e164": "+16172252821", "national": "(617) 225-2821", "international": "+1 617-225-2821", "rfc3966": "tel:+1-617-225-2821" }, "carrier": { "mobile_country_code": "", "mobile_network_code": "", "name": "Verizon", "type": "fixed", "ported": "no" }, "resource_uri": "/v1/Number/+16172252821?type=carrier" } ### Error { "api_id": "", "error_code": 403, "message": "Account is forbidden from accessing resource." } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Plivo PHLO | Plivo Docs PHLO ==== Overview -------- Plivo High Level Objects (PHLO, pronounced “flow”) is a visual workflow design studio. It provides building blocks that let you create custom voice and SMS applications without writing program code. Instead, you drag and drop components onto a canvas and connect them to create custom workflows. That lets you build applications quickly, and you can speed development time further by using PHLO templates — prebuilt workflows for common use cases. PHLO terminology ---------------- ### Canvas The canvas is the space where you place and connect components to create a PHLO. If a PHLO grows to cover the visible canvas, you can scroll the canvas in any direction to declutter the display. ### Component Components are PHLO’s building blocks. You drag and drop components to the canvas to create nodes, then connect the nodes to create workflows. You can view a list of all components on the [Components Library](/docs/phlo/components/) page. ### Node A node is an instance of a component that has been placed on the canvas. Each node must have a unique name within the PHLO. ### States States are properties that a component is set to or based on for each action. Each component has one input state and at least one output state. ### Configuration and Information tabs Every node has a set of default configuration values associated with it. When you click on a node you can view its configuration in the **Configuration** tab on a panel on the right of the canvas. To view the list of configuration options available for the node, click the **Information** tab at the top of that panel. The Information tab displays information about the node, its default variables, and node-specific options and states. You can change a node’s configuration by entering values in the Configuration tab. After you make changes, you must validate the node by clicking on **Validate** at the bottom of the panel. The side panel will display validation errors, if any, or slide off the canvas if the node is validated. You must correct all validation errors before you save the PHLO. ### Triggers Triggers let you manage an ongoing call. There are four types of triggers: * Call * Hold * Transfer * Hangup Creating PHLOs -------------- You can create a PHLO either by using a blank canvas or by using a packaged templates. ### Building a PHLO using a blank canvas 1. In the Plivo console, click the [**PHLO**](https://console.plivo.com/phlo/list/) icon. The PHLO page will appear and display your existing PHLOs. If you’re creating your first PHLO, the PHLO page will be empty. 2. Click the **Create New PHLO** button to start building a new PHLO. 3. In the **Choose your use case** window, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger the start of a workflow with either an incoming SMS message or voice call or an API request. 4. From the Components list at the left, drag and drop a component onto the canvas to create a new node. The Configurations tab will appear — see [Configuring PHLO components](/docs/phlo/#configuring-phlo-components) . 5. Click **Validate** to save the configurations for the node. 6. Drag more components onto the canvas as appropriate. Connect nodes in a logical sequence. For more information, see [Connecting PHLO components](/docs/phlo/#connecting-phlo-components) . 7. Enter a unique name for the PHLO, then click **Save**. You can then trigger the PHLO, as we talk about below. ### Building a PHLO using a template 1. In the Plivo console, click the [**PHLO**](https://console.plivo.com/phlo/list/) icon. The PHLO page will appear and display your existing PHLOs. If you’re creating your first PHLO, the PHLO page will be empty. 2. Click the **CREATE NEW PHLO** button to start building a new PHLO. 3. In the **Choose your use case** window, select one of the available templates. The PHLO canvas will appear with all of the nodes that are part of the use case connected appropriately. 4. If you need to add more steps to the workflow, then from the Components list at the left drag and drop a component onto the canvas to create a new node. Each time you add a node the Configurations tab will appear — see [Configuring PHLO components](/docs/phlo/#configuring-phlo-components) . 5. Connect nodes in a logical sequence. For more information, see [Connecting PHLO components](/docs/phlo/#connecting-phlo-components) . 6. Enter a unique name for the PHLO, then click **Save**. You can then trigger the PHLO, as we talk about below. Connecting PHLO components -------------------------- After you’ve added components to the PHLO canvas, you must create connections between the nodes to complete the workflow. Defining a command to a response is as simple as connecting the output state of one node to the input state of another. The output state is the command and the input state is the response. Each node has a predefined set of output states. To connect PHLO components, on the PHLO Canvas, click and drag the output state of a node to the input state of another node. For example, here’s an IVR menu that shows the connection between output and input states. ![Example](https://s3.amazonaws.com/plivo_blog_uploads/static_assets/images/docs/example.png) In this example, the **IVR Menu\_1** node has four output states: * No Input * Wrong Input * 1 * 2 The IVR Menu\_1 node’s **No Input** output state connects to the Play Audio\_1 input state at the top of the node. Every node has a input state except the Start node. Once you’ve connected all the nodes on your PHLO canvas, make sure you’ve configured the components, as we talk about in the next section. Configuring PHLO components --------------------------- You must configure every node to make sure the workflow works as intended. You can access a node’s Configurations tab by clicking on it on the canvas. The adjacent Information tab in the right panel explains the configuration and variables available for the node. PHLO supports two types of variables: global variables and variables specific to components. ### Global variables You configure global variables by defining key-value pairs in the Start node of the PHLO. Connect the Start node to the component in which you want to use the global variables, then use two curly brackets to view all available variables. Scroll through the list and select the variable you want to use. ### Variables specific to components Each component has a list of predefined variables that you can use. For more information on the components and their default variables and configurations, see the [PHLO components library](/docs/phlo/components/) page. After you change a node’s configuration, click **Validate** to make sure there are no errors in the configuration. PHLO will display a message if it finds an error. Triggering a PHLO ----------------- You can trigger a PHLO with an incoming call or SMS message or with an outgoing API call. If you plan to trigger a PHLO for an incoming call or message, you must add the PHLO to a Plivo number. If you need to buy a phone number, visit [Phone Numbers](https://console.plivo.com/active-phone-numbers/) on the console and click **Buy Number**. On this page you can search for available phone numbers based on country, type (local, national, mobile, or toll-free), and capability (voice, SMS, or MMS), then click **Buy Number** for the number that you want to purchase. ### Triggering a PHLO using a phone number Once you’ve created and configured a PHLO, assign your PHLO to a number. 1. Visit [Phone Numbers](https://console.plivo.com/active-phone-numbers/) on the console. 2. On the Numbers page, under Your Numbers, click the phone number you want to use for the PHLO. 3. In the Number Configuration section, select **PHLO**  from the application type drop-down list. 4. From the PHLO Name drop-down list, select the PHLO you want to use with the phone number. 5. Click on **Update Number**. Make a call or send an SMS message to the phone number to test your PHLO. ### Triggering a PHLO using an API request Once you’ve created and configured your PHLO, copy the PHLO URL either by clicking on the button in the upper right corner above the PHLO canvas or from the list on the [PHLO](https://console.plivo.com/phlo/list/) page of the console. ![PHLO Listing](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg)Integrate the PHLO into your application workflow by making an API request to the PHLO URL. You can trigger an API request with or without a payload depending on how the PHLO is set up. You can configure static payload values (from, to, etc.) on the PHLO console. Alternately, you can define the payload keys as [Liquid](https://shopify.github.io/liquid/) templates on the PHLO console and pass the values dynamically at runtime for execution. ### Code sample — without payload * [Python](#run-a-phlo-python) * [Ruby](#run-a-phlo-ruby) * [Node.js](#run-a-phlo-node) * [PHP](#run-a-phlo-php) * [Java](#run-a-phlo-java) * [Go](#run-a-phlo-go) * [.NET](#run-a-phlo-net) * [Curl](#run-a-phlo-curl) 1 2 3 4 5 6 7 8 9 import plivo auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() print str(response) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 require 'rubygems' require 'plivo' include Plivo AUTH_ID = 'AUTH_ID' AUTH_TOKEN = 'AUTH_TOKEN' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new begin phlo = client.phlo.get('phlo_id') response = phlo.run() puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = 'auth-id'; var authToken = 'auth-token'; var phloId = 'PHLO_ID'; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import java.io.IOException; public class Example { private static final String authId = ""; private static final String authToken = ""; private static PlivoClient client = new PlivoClient(authId, authToken); public static void main(String[] args) throws IOException, PlivoRestException { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); PhloUpdateResponse response = Phlo.updater(phloId).payload().run(); } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 package main import ( "fmt" "plivo-go" ) const authId = "" const authToken = "" const phloId = "phlo_id" func main() { testPhloRunWithoutParams() } func testPhloRunWithoutParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } response, err := phloGet.Run(nil) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 using System; using Plivo; namespace test_PHLO_dotnet { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = "phlo_id"; var phlo = phloClient.Phlo.Get(phloID); Console.WriteLine(phlo.Run()); } } } 1 2 curl -i --user AUTH_ID:AUTH_TOKEN \ https://phlorunner.plivo.com/v1/account/{auth_id}/phlo/{phlo_id} ### Code sample — with payload * [Python](#run-a-phlo-payload-python) * [Ruby](#run-a-phlo-payload-ruby) * [Node.js](#run-a-phlo-payload-node) * [PHP](#run-a-phlo-payload-php) * [Java](#run-a-phlo-payload-java) * [Go](#run-a-phlo-payload-go) * [.NET](#run-a-phlo-payload-net) * [Curl](#run-a-phlo-payload-curl) 1 2 3 4 5 6 7 8 9 10 import plivo auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "+12025550000","to" : "+12025551111"} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) print str(response) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 require 'rubygems' require 'plivo' include Plivo AUTH_ID = 'AUTH_ID' AUTH_TOKEN = 'AUTH_TOKEN' client = Phlo.new(AUTH_ID, AUTH_TOKEN) begin phlo = client.phlo.get('phlo_id') #parameters set in PHLO - params params = { from: '9999999999', to: '0000000000' } response = phlo.run(params) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = 'auth-id'; var authToken = 'auth-token'; var phloId = 'PHLO_ID'; var phloClient = phlo = null; var payload = { from: '19999999999', to: '18888888888' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(["field1" => "value1", "field2" => "value2"]); // These are the fields entered in the PHLO console print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import java.io.IOException; public class Example { private static final String authId = ""; private static final String authToken = ""; private static PlivoClient client = new PlivoClient(authId, authToken); public static void main(String[] args) throws IOException, PlivoRestException { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); Map payload = new HashMap<>(); payload.put("phone", "+12025550000"); payload.put("to", "+12025551111"); PhloUpdateResponse response = Phlo.updater(phloId).payload(payload).run(); } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 package main import ( "fmt" "plivo-go" ) const authId = "" const authToken = "" const phloId = "phlo_id" func main() { testPhloRunWithParams() } func testPhloRunWithParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } //pass corresponding from and to values type params map[string]interface{} response, err := phloGet.Run(params{ "from": "12025550000", "to": "12025551111", }) if err != nil { println(err) } fmt.Printf("Response: %#v\n", response) } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 using System; using Plivo; namespace test_PHLO_dotnet { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = "phlo_id"; var phlo = phloClient.Phlo.Get(phloID); var data = new Dictionary { { "from", "19999999999" }, { "to", "18888888888" } }; Console.WriteLine(phlo.Run(data)); } } } 1 2 3 4 5 curl --request POST \ --user AUTH_ID:AUTH_TOKEN \ --url 'https://phlorunner.plivo.com/v1/account/{auth_id}/phlo/{phlo_id}' \ --header 'Content-Type: application/json' \ --data '{"from": "12025550000","to": "12025551111"}' You can get the Auth ID and Auth Token you need for this code from the overview page of the [console](https://console.plivo.com/dashboard/) . ![AuthID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You can install a [server SDK](/docs/sdk/) to help you code, and [set up a development environment](/docs/sdk/server/setting-up-dev-environment/) . Use case guides --------------- We’ve put together some use cases guides to help you get started with some common tasks: * [Voice notification](/docs/voice/use-cases/voice-notification/node/) * [Voice alerts](/docs/voice/use-cases/voice-alerts/node/) * [Pinless conference](/docs/voice/use-cases/call-conference/node/) * [Conference with PIN](/docs/voice/use-cases/conference-with-pin/node/) * [IVR](/docs/voice/use-cases/ivr/node/) * [Call forwarding](/docs/voice/use-cases/call-forwarding/node/) * [Voice survey](/docs/voice/use-cases/voice-survey/) * [Voicemail](/docs/voice/use-cases/voicemail/node/) * [SMS alerts](/docs/messaging/use-cases/sms-alert/node/) * [SMS notifications](/docs/messaging/use-cases/sms-notification/node/) * [SMS survey](/docs/messaging/use-cases/sms-survey/node/) * [SMS autoresponder](/docs/messaging/use-cases/sms-autoresponder/node/) All of these use cases are also available as PHLO templates — predefined workflows that help you build your applications faster. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Overview | Plivo Developers Overview ======== The Plivo Verify API lets you programmatically authenticate users via 2FA using SMS and voice calls. * Programmatically send one-time passwords (OTP) to users in 190+ countries. Our direct carrier connections and optimized routing ensure high delivery rates and low latency. * Take advantage of competitive pricing. Simple usage-based billing means you pay only for what you use. * Add verification to your applications in minutes with ready-to-use templates and Getting Started guides. ### Life of a 2FA code Here’s how Plivo generates and uses 2FA code. “Code” is just another way of saying “one-time password.” 1. Your application uses Plivo’s Verify API to generate a code for your user. 2. Plivo sends the code to telecom networks using it’s global network to be delivered to the destination phone number. 3. Plivo returns the delivery status to your application. 4. The user enters code they received in your web page or application. 5. You validate that code using the Verify API. ### How to use Verify To start sending codes, you must first [set up an application](/docs/verify/concepts/applications/) on the Plivo console. An application dictates factors such as the length of the OTP, message expiry interval, and the template to be used. A template defines the context in which the OTP is delivered: “Your ${brand} verification code is ${code},” for example. Once your application is set up, you can start sending messages to users by specifying the application ID and a user’s phone number. Plivo will generate an OTP on your behalf and send it per the template that you specified in your application. You can choose the channels that you want to use — SMS, voice, or both. Plivo provides callbacks that tell your application whether the OTP was delivered. When a user enters an OTP in a web page or an application, you can validate it using the same Verify API. And you can fetch details of one or all OTP requests by using our APIs or checking the console. ### Conclusion The Verify API makes it easy to send OTPs to users over Plivo’s enterprise-grade cloud communications platform. With Verify, you don’t have to manage compliance or security issues. We’ve written several resources to help you get started: * [Setting up your Verify application](/docs/verify/concepts/applications/) * [Sending and validating codes](/docs/verify/concepts/send-and-validate-code/) * [API documentation](/docs/verify/api/overview/) Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Number Masking vs Lookup- Get Started with Number Masking API Get Started with Number Masking API =================================== Overview -------- Phone number masking hides the phone numbers of parties in a call from each other. Many businesses find it advantageous to anonymize communication between two parties. * **Food/grocery and ecommerce delivery apps** connect a delivery agent to a customer. * **Ride-hailing apps** connect a driver to a person who ordered a ride. * **Classified ad listing apps** connect a seller to a buyer, or a service provider to a customer. Plivo’s Number Masking API handles both virtual number assignment and call flow management. You use it by sending the real phone numbers of parties over an API request. Plivo will respond back with a virtual number from your account which you can use for hosting the masked session. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with PHP using PHP Server | Plivo Voice * [PHP Server](/docs/voice/quickstart/php/) * [PHP Laravel](/docs/voice/quickstart/php-laravel/) Get Started with PHP Using PHP Server ===================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your PHP dev environment ------------------------------- You must set up and install PHP and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) or [Windows](https://www.php.net/manual/en/install.windows.php) or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install the Plivo PHP SDK * Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp * To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php * Alternatively, download this [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(["from" => "", "to" => ""]); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ php TriggerPhlo.php Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both PHLO and API/XML on our documentation pages. Install PHP and the Plivo PHP SDK --------------------------------- You must set up and install PHP and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) , [Windows](https://www.php.net/manual/en/install.windows.php) , or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install the Plivo PHP SDK Create a project directory and change into it. $ mkdir myphpapp $ cd myphpapp To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a PHP server to handle outbound calls Create a file called `MakeCall.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 "; $auth_token = ""; $client = new RestClient($auth_id, $auth_token); $response = $client->calls->create('', [''], 'https://s3.amazonaws.com/static.plivo.com/answer.xml',); print_r($response); **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use $\_ENV or putenv/getenv to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. $ php MakeCall.php Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a PHP server to handle incoming calls Create a file called `receive_call.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 addSpeak($speak_body); Header('Content-type: text/xml'); echo($response->toXML()); ?> Save the the file and start the server. $ php -S localhost:8000 You should see your basic server application in action at http://localhost:8000/receive\_call.php. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_phpapp.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a PHP server to forward calls Create a file called `forward_call.php` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 "https://.com/dial_status/", 'method' => "POST", 'redirect' => "true" ); $dial = $response->addDial($params); $number = ""; $dial->addNumber($number); Header('Content-type: text/xml'); echo($response->toXML()); Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-php-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the PHP application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Voice Notifications Using Node.js | Plivo Docs * [Node](/docs/voice/use-cases/voice-notification/node/) * [Ruby](/docs/voice/use-cases/voice-notification/ruby/) * [Python](/docs/voice/use-cases/voice-notification/python/) * [PHP](/docs/voice/use-cases/voice-notification/php/) * [.NET](/docs/voice/use-cases/voice-notification/dotnet/) * [Java](/docs/voice/use-cases/voice-notification/java/) * [Go](/docs/voice/use-cases/voice-notification/go/) Voice Notifications Using Node.JS ================================= Overview -------- This guide shows how to send audio notifications using voice calls. You can play recorded audio when the call recipient answers or use text-to-speech, as we show here, combining static text with dynamic information that Plivo gets from a variable. You can use voice notification for use cases such as: * Order notification * Booking status * Delivery status * Flight cancellation/rescheduling * Two-factor authentication/one-time password * New offer notification * Account balance notification Implement voice notification either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a PHLO to send voice notifications with a few clicks on the PHLO canvas. How it works ------------ Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time triggering a PHLO with Node.js, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-phlo/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * Click the **Start** node to open the Configurations tab, then enter the information to retrieve from the HTTP Request payload — in this case, the From and To numbers for the call, and an item number. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. This adds an Initiate Call node onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration tab of the Initiate Call node, give the node a name. To enter values for the **From** and **To** fields, enter two curly brackets to view all available variables, and choose the appropriate ones. The values for the numbers will be retrieved from the HTTP Request payload you defined in the Start node. * Validate the configuration by clicking **Validate**. Do the same for each node as you go along. * Next, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane. * Audio playback can either be static or dynamic. You define a static payload by specifying values when you create the PHLO, and a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * On the **Play Audio** Configuration tab, enter a static message (for example, “Your order has been successfully placed”) in the **Speak Text** field, with a variable to include the dynamic text. Enter two curly brackets to view all available variables. Choose the item number you defined in the Start node configuration tab. * After you complete and validate the node configurations, give the PHLO a name by clicking in the upper left, then click **Save**. Your completed PHLO should look like this: ![Voice Notification](https://docs.plivo.com/assets/posts/images/phlo/voice-notification.jpg) Your PHLO is now ready to test. Trigger the PHLO ---------------- You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. ### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . ### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code to the PHLO when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { from: '', to: '' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). Test ---- Save the file and run it. node TriggerPhlo.js Here’s how to use Plivo APIs and XML to implement voice notifications. How it works ------------ ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/notification.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations, your order was successfully placed This code instructs Plivo to say, “Congratulations, your order was successfully placed” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) . Create a voice notification application in Node.js -------------------------------------------------- Create a file called `Makecall.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 var plivo = require('plivo'); (function main() { 'use strict'; var client = new plivo.Client("",""); client.calls.create( "", // from "", // to "https://s3.amazonaws.com/static.plivo.com/notification.xml", // answer url { answerMethod: "GET", }, ).then(function (response) { console.log(response); }, function (err) { console.error(err); }); })(); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables, to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and fetch them while initializing the client. Test ---- Save the file and run it. $ node Makecall.js Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Applications | Plivo Developers Applications ============ Before you start sending 2FA codes to your users, you first need to [create a Verify application on the Plivo console](https://console.plivo.com/verify/applications/) . An application has several properties: * **UUID**: A unique identifier for your application, automatically generated by Plivo. You must specify the UUID when triggering a request for an OTP. * **Alias**: A friendly name for your application. * **Supported channels**: All applications by default support SMS and voice channels; you can disable voice. * **Brand name** * **Default template**: Plivo lets you select a template for your application from a list of predefined templates for all types of 2FA use cases. A template might look like “Your ${brand} verification code is ${code}.” When you send a code using an application that uses this template, Plivo will replace the variables “brand” and “code” with the brand specified in the application and a code generated with the type and length specified in the application. * **Code properties**: Plivo lets you configure four properties for your application. * **Length**: Indicates the length of the OTP. * **Expiry**: Indicates an expiry interval for each OTP, after which the code will be considered expired. * **Attempts**: Indicates the maximum number of attempts to make to a recipient within the expiry period. Setting a limit on attempts can be helpful in keeping your costs down by avoiding multiple SMS or voice calls to a number that’s inactive or unresponsive. * **Android AppHash**: You can configure your Android app’s hash string to a verify application. This will enable automatic SMS verification in your Android app, eliminating the need for your user to manually copy and paste. To calculate your hash, follow Google’s instructions for [computing your app’s hash string](https://developers.google.com/identity/sms-retriever/verify?fbclid=IwZXh0bgNhZW0CMTEAAR0142V7eVOrRnfSsBU79b9Sonbp6XYbPK42T-AM4Qtp6e6OvrtfWq5Dj4M_aem_ZmFrZWR1bW15MTZieXRlcw#computing_your_apps_hash_string) . ### Create Application - part 1 ![](/uploads/screenshot-2023-08-01-at-3-09-46-am.png) ### Create Application - part 2 ![](/uploads/screenshot-2023-08-01-at-3-11-47-am.png) ### Things to keep in mind while creating an application Most businesses will need to create just one application, as 2FA codes for a business tend to be uniform except for the code itself. However, you might want to use four-digit OTPs for your login experience and six-digit OTPs for your checkout experience, or vice versa. Similarly, you might want to use only SMS for logins but SMS and voice channels for payments. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with PHP Using Laravel Framework | Plivo Voice * [PHP Server](/docs/voice/quickstart/php/) * [PHP Laravel](/docs/voice/quickstart/php-laravel/) Get Started with PHP Using Laravel Framework ============================================ Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your PHP Laravel dev environment --------------------------------------- You must set up and install PHP, Laravel, and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) or [Windows](https://www.php.net/manual/en/install.windows.php) or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install Laravel and create a Laravel project * Install Laravel. $ composer require laravel/installer * Create a project directory and change into it. $ mkdir mylaravelapp $ cd mylaravelapp * Create a Laravel project. $ composer create-project laravel/laravel quickstart --prefer-dist This command creates a quickstart directory with the necessary folders and files for development. ### Install the Plivo PHP SDK * To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php * Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(); echo json_encode($response); } catch (PlivoRestException $ex) { echo json_encode($ex); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit app/http/controllers/phloController.php and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 ", ""); $phlo = $client->phlo->get(""); try { $response = $phlo->run(["from" => "", "to" => ""]); echo json_encode($response); } catch (PlivoRestException $ex) { echo json_encode($ex); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test #### Add a route Edit routes/web.php and add this line at the end of the file. Route::match(['get', 'post'], '/triggerphlo', 'PhloController@triggerPhlo'); **Note:** If you’re using Laravel 8 then you need to use the fully qualified class name for your controllers. For example: Route::match(['get', 'post'], '/triggerphlo', 'App\Http\Controllers\PhloController@triggerPhlo'); Save the file and run your code. $ php artisan serve Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both PHLO and API/XML on our documentation pages. Install PHP, Laravel, and the Plivo PHP SDK ------------------------------------------- You must set up and install PHP, Laravel, and Plivo’s PHP SDK before you make your first call. ### Install PHP Follow the official PHP instructions to download and install PHP on [macOS](https://php.net/manual/en/install.macosx.php) , [Windows](https://www.php.net/manual/en/install.windows.php) , or [Debian Linux](https://www.php.net/manual/en/install.unix.debian.php) , or use your favorite package manager to install PHP on any Linux distro. ### Install Composer We recommend using Composer, a dependency manager for PHP, as the package manager for your PHP projects. * [macOS](#osx) * [Linux](#linux) * [Windows](#windows) * Download the latest version of [Composer](https://getcomposer.org/download/) . * Run this command in Terminal to run Composer. $ php ~/Downloads/composer.phar --version **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make it executable. $ cp ~/Downloads/composer.phar /usr/local/bin/composer $ sudo chmod +x /usr/local/bin/composer Move the file to bin directory. * To check whether the path includes /usr/local/bin, type $ echo $PATH If the path is different, update it. $ export PATH = $PATH:/usr/local/bin $ source ~/.bash_profile **Note:** If your path doesn’t include /usr/local/bin, we recommend adding it so that you can access it globally. * Download the Composer installer. $ curl -sS https://getcomposer.org/installer | php * Make the composer.phar file executable. $ chmod +x composer.phar **Note:** PHAR (PHP archive) is an archive format for PHP that can be run on the command line. * Make Composer globally available for all system users. $ mv composer.phar /usr/local/bin/composer * Download and run the [Windows Installer](https://getcomposer.org/download/) for Composer. **Note:** Allow the installer to make changes to your php.ini file. * If you have any terminal windows open, close them all and open a fresh terminal instance. * Run the Composer command. $ composer -V ### Install Laravel and create a Laravel project Install Laravel. $ composer require laravel/installer Create a project directory and change into it. $ mkdir mylaravelapp $ cd mylaravelapp Create a Laravel project. $ composer create-project laravel/laravel quickstart --prefer-dist This command creates a quickstart directory with the necessary folders and files for development. ### Install the Plivo PHP SDK To install the most recent release of the Plivo PHP SDK, run $ composer require plivo/plivo-php Alternatively, download the [source](https://github.com/plivo/plivo-php/) and run $ composer install This command generates autoload files, which you can include in your PHP source code to start using the SDK. Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Create a Laravel controller to handle outbound calls Change to the project directory and create a Laravel controller to handle outbound calls. $ php artisan make:controller VoiceController This command generates a controller named VoiceController in the app/http/controllers/ directory. Edit the file and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 "; $auth_token = ""; $client = new RestClient($auth_id, $auth_token); $response = $client->calls->create('', [''], 'https://s3.amazonaws.com/static.plivo.com/answer.xml',); header('Content-Type: application/json'); echo json_encode($response); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use $\_ENV or putenv/getenv to store environment variables and retrieve them when initializing the client. ### Add a route Edit routes/web.php and add this line at the end of the file. Route::match(['get', 'post'], '/makecall', 'VoiceController@makeCall'); **Note:** If you’re using Laravel 8, use the fully qualified class name for your controllers — for example: Route::match(['get', 'post'], '/sendSMS', 'App\Http\Controllers\SMSController@sendSMS'); To disable CSRF verification, add the route of the application to the except array in app/Http/Middleware/VerifyCsrfToken.php. ### Test Run your code. $ php artisan serve Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Laravel server to handle incoming calls Edit app/http/controllers/VoiceController.php and paste into it this code in the VoiceController class after the makeCall function. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 addSpeak($speak_body); Header('Content-type: text/xml'); echo $response->toXML(); } } ### Add a route Edit routes/web.php and add this line at the end of the file. Route::match(['get', 'post'], '/receivecall', 'VoiceController@receiveCall'); Run the code. $ php artisan serve You should see your basic server application in action at http://localhost:8000/receivecall/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) You can check the app in action at https://3b3e783f.ngrok.io/receivecall and check the XML response. ![sample XML](https://docs.plivo.com/assets/posts/images/voice/quickstart/laravel/xml.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_phpapp.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Update the Laravel controller Edit app/http/controllers/VoiceController.php and paste into it this code in the VoiceController class after the receiveCall function. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 "https://.com/dial_status/", 'method' => "POST", 'redirect' => "true" ); $dial = $response->addDial($params); $number = ""; $dial->addNumber($number); Header('Content-type: text/xml'); echo $response->toXML(); } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). ### Add a route Edit routes/web.php and add this line at the end of the file. Route::match(['get', 'post'], '/forwardcall', 'VoiceController@forwardCall'); If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-php-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Laravel controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/php/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Voice Alerts using Node.js | Plivo Docs * [Node](/docs/voice/use-cases/voice-alerts/node/) * [Ruby](/docs/voice/use-cases/voice-alerts/ruby/) * [Python](/docs/voice/use-cases/voice-alerts/python/) * [PHP](/docs/voice/use-cases/voice-alerts/php/) * [.NET](/docs/voice/use-cases/voice-alerts/dotnet/) * [Java](/docs/voice/use-cases/voice-alerts/java/) * [Go](/docs/voice/use-cases/voice-alerts/go/) Voice Alerts Using Node.JS ========================== Overview -------- This guide shows how to make voice calls to alert customers to critical issues that require immediate attention. You can play recorded audio when the call recipient answers or use text-to-speech. You can then take action based on a dialpad key they press in response. You can set different actions if the call is not answered, if the line is busy, or if you reach voicemail. You can send voice alerts either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time triggering a PHLO with Node.js, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-phlo/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * Click the **Start** node to open the Configuration tab to the right of the canvas, then enter the information to retrieve from the HTTP Request payload — in this case, from and to numbers and a database server name. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. This adds an **Initiate Call** node onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration tab of the **Initiate Call** node, give the node a meaningful name. To enter values for the From and To fields, start typing two curly brackets. PHLO will display a list of all available variables; choose the appropriate ones. When you use variables in a PHLO, the values are retrieved from the HTTP Request payload you defined in the Start node. * Validate the configuration by clicking **Validate**. Every time you finish configuring a node, click **Validate** to check the syntax and save your changes. * Next, drag and drop the **IVR Menu** component onto the canvas. Draw a line to connect the **Answered** trigger state of the **Initiate Call** node to the **IVR Menu** node. * Click the **IVR Menu** node to open its Configuration tab. Rename the node to **Gather\_Input**. You can rename nodes as you like to improve your PHLO’s readability. For this example, select **1** and **2** as the allowed choices, and enter a message to play to the user in the Speak Text field. If you like, you can also configure the Language and Voice fields for the message. * Because we specified two allowed choices in the IVR menu, we need to drag and drop three **Play Audio** nodes onto the canvas — one for each option, plus one for invalid input. Rename the nodes **Invalid\_Input\_Prompt**, **Resolved\_Prompt**, and **Escalation\_Prompt** in their Configuration tabs, and enter appropriate messages in their Prompt fields. * From the **Gather\_Input** node, connect the **Wrong Input** trigger state to the **Invalid\_Input\_Prompt** node. * From the **Invalid\_Input\_Prompt** node, connect the **Prompt Completed** trigger state back to the **Gather\_Input** node. This sends the user back to the IVR menu if they press an incorrect option, or if they don‘t press any key. * From the **Gather\_Input** node, connect the **1** and **2** trigger states to the **Resolved\_Prompt** and **Escalation\_Prompt** nodes. * Configure all three **Play Audio** nodes to each play a relevant message to the user. Audio playback can either be static or dynamic or a combination of the two; for example, you could specify in the Speak Text field “Your status is,” followed by a variable to include the dynamic text. You can bring up a list of available variables by typing two curly brackets in the Speak Text field. * Drag and drop the **Initiate Call** component onto the canvas and rename the node to **Escalation\_Call**. * Draw a line to connect the **Prompt Completed** trigger state of the **Escalation\_Prompt** node to the **Escalation\_Call** node. This triggers a call to another phone number and announces the alert. You can set up any number of escalation numbers by creating similar nodes for each phone number. * Draw a line to connect the **Answered** trigger state of the **Escalation\_Call** node back to the **Gather Input** node. This will play the same prompt to the user after the original escalation call is answered and completed and give the user another chance to either resolve the call or escalate it. * After you complete and validate all the node configurations, give the PHLO a name by clicking in the upper left, then click **Save**. Your completed PHLO should look like this: ![Voice Alert](https://docs.plivo.com/assets/posts/images/phlo/voice-alert.jpg) Your PHLO is now ready to test. Trigger the PHLO ---------------- You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. ### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = 'phlo_id'; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . ### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code to the PHLO when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Now, create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { from: '', to: '' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). Test ---- Save the file and run it. node TriggerPhlo.js Here’s how to use Plivo APIs and XML to implement voice alerts. How it works ------------ ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/alert.xml as an answer URL to test your first outgoing call. The file contains this XML code: Your database is out of memory. Press 1 to resolve or 2 to escalate. This code instructs Plivo to say, “Your database is out of memory. Press 1 to resolve or 2 to escalate” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) . Create a voice alerts application in Node.js -------------------------------------------- Create a file called `Makecall.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 var plivo = require('plivo'); (function main() { 'use strict'; var client = new plivo.Client("",""); client.calls.create( "", // from "", // to "https://s3.amazonaws.com/static.plivo.com/alert.xml", // answer url { answerMethod: "GET", }, ).then(function (response) { console.log(response); }, function (err) { console.error(err); }); })(); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables, to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and fetch them while initializing the client. Test ---- Save the file and run it. $ node Makecall.js Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Python Using Flask Framework| Plivo Voice * [Python & Flask](/docs/voice/quickstart/python-flask/) * [Python & Django](/docs/voice/quickstart/python-django/) * [Python & FastAPI](/docs/voice/quickstart/python-fastapi/) * [Python & Sanic](/docs/voice/quickstart/python-sanic/) Get Started with Python Using Flask Framework ============================================= Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Python Flask dev environment ---------------------------------------- You must set up and install Python, Flask, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Flask and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install the modules using [pip](https://pip.pypa.io/en/latest/) . pip install flask plivo Alternatively, you can download the Plivo source code from [this repo](https://github.com/plivo/plivo-python/) and run python setup.py install We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using `sudo` with your commands and overwriting dependencies. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 import plivo auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() print str(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 import plivo auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "","to" : ""} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) print str(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ python trigger_phlo.py Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both PHLO and API/XML on our documentation pages. Install Python, Flask, and the Plivo Python SDK ----------------------------------------------- You must set up and install Python, Flask, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Flask and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install Flask and the Plivo Python SDK using [pip](https://pip.pypa.io/en/latest/) . $ pip install flask plivo Alternatively, you can download the [source code](https://github.com/plivo/plivo-python/) and run $ python setup.py install We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using sudo with your commands and overwriting dependencies. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a Flask server to handle outbound calls Create a file called `makecall.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 import plivo client = plivo.RestClient('','') response = client.calls.create( from_='', to_='', answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml', answer_method='GET', ) print(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.environ to store environment variables and retrieve them when initializing the client. ### Test Save the file and run your code. $ python makecall.py Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Flask server to handle incoming calls Create a file called `receive_call.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 from flask import Flask, Response from plivo import plivoxml app = Flask(__name__) @app.route('/receive_call/', methods=['GET','POST']) def speak_xml(): # Generate a Speak XML document with the details of the text to play on the call response = (plivoxml.ResponseElement() .add(plivoxml.SpeakElement('Hello, you just received your first call'))) return Response(response.to_string(), mimetype='application/xml') if __name__ == "__main__": app.run(host='0.0.0.0', debug=True) Save the file and run the code. $ python receive_call.py You should see your basic server application in action at http://localhost:5000/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (8000 in this case): ./ngrok http 8000 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Ngrok CLI](https://docs.plivo.com/assets/posts/images/quickstart/ngrok_cli.png) You can check the app in action at https://6ea358b0f703.ngrok.io/receivecall/ and check the XML response. ![Sample XML response](https://docs.plivo.com/assets/posts/images/quickstart/sample_xml_response.png) ### Create a Plivo application to receive calls Associate the Flask server you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call.php/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_app.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Flask server to forward calls Create a file called `forward_call.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 from flask import Flask, request, make_response, Response from plivo import plivoxml app = Flask(__name__) @app.route('/forward_call/', methods=['GET', 'POST']) def forwardcall(): response = plivoxml.ResponseElement() response.add( plivoxml.DialElement().add( plivoxml.NumberElement(''))) return(response.to_string()) if __name__ == '__main__': app.run(host='0.0.0.0', debug=True) Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-python-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Flask server you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Send and validate code | Plivo Developers Send and validate code ====================== Before you start writing your integration code, read our getting started and [setup](/docs/verify/concepts/applications/) guides. ### What’s a session? Plivo’s Verify API is designed around the concept of sessions. Each interaction with a user is a session. A session can have multiple attempts. Let’s say you send an OTP to a user at 10:00 a.m. with an expiry of 10 minutes. This activity initiates a session between you and your user that will expire at 10:10 a.m. You can send one or more requests to this user in this duration, and all the attempts will be considered part of the same session. Plivo lets you choose the length of your sessions and numbers of attempts that you can make to one destination within a session. All requests within a session deliver the same OTP to the user. ### Send 2FA code Once you’ve set up an application, you can send OTPs to users with a simple API request, specifying the application to use, the intended destination number, and the channel that you want to use. Plivo will generate a code for you and send it to the specified destination using the specified channel. If your code is not delivered in the first SMS attempt, you can try sending another SMS or try voice as an alternate route using the same API and Plivo will attempt to deliver the same OTP. You can also specify a URL for callbacks and Plivo will send you status updates on this URL. **Code** * [Curl](#send-and-validate-code-curl) 1 2 3 4 5 6 7 8 9 10 curl -i --user auth_id:auth_token \ -H "Content-Type: application/json" \ -d '{ "app_uuid":"", "recipient": "", "url":"", "channel":"sms", "method":"POST" }' \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/ #### Response { "api_id": "3335cb16-d297-4e00-a5e6-66d2bb03b323", "message": "Session initiated", "session_uuid": "8e712097-8090-4644-81e7-8f4265d8354e" } ### Validate code When your user enters the OTP you sent into a form for authentication, you can validate it using Verify’s validation API, which requires you to pass the session UUID and the OTP that you want to validate. You can attempt no more than 10 validations for a session, to stop brute-force hacking attacks. **Code** * [Curl](#validate-code-curl) 1 2 3 4 5 6 curl -i --user auth_id:auth_token \ -H "Content-Type: application/json" \ -d '{ "OTP": "" }' \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/ #### Response { "api_id": "e7af31b5-a7cb-40d6-a3ab-122fdcc9f0fe", "message": "session validated successfully.", } ### Other features You can also fetch details of your session or multiple sessions at once by using APIs. The same details are also available [on the Plivo console](https://console.plivo.com/verify/logs/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Voice Survey using PHLO | Plivo Docs Voice Survey ============ We use voice surveys for collecting information from customers like satisfaction scores of a service provided. Plivo’s PHLO allows you to create and configure a voice survey system for your business. An API call triggers the PHLO to call the customer with survey questions. You can set up PHLO with multi-level survey questions based on the key pressed. You can also configure and receive the responses on your app for consolidation. Creating the Use Case using PHLO -------------------------------- With PHLO, you can quickly create a workflow that suits your use case. To use PHLO, make sure to register and log on to [Plivo Console](https://console.plivo.com/) . Use the following components to create this PHLO: * Initiate Call * IVR Menu * Play Audio * HTTP Request When you send an API request to the PHLO, it triggers a call to the user using the **Initiate Call** component. Once the user answers the call, the **Play Audio** component plays an audio to the user. The call will disconnect automatically after the playback audio is completed. **Note:** The Callback function provides the user details required to make the call. To create this PHLO 1. On the top navigation bar, click **PHLO**.The PHLO page will appear and display your existing PHLOs, if any exist. If this is your first PHLO, then the PHLO page will be empty. 2. Click **CREATE NEW PHLO** to build a new PHLO. 3. From the **CREATE A NEW PHLO** window, select **Build on a blank canvas**, and then click **CREATE PHLO**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. You can choose between the four available trigger states of the Start node; Incoming SMS, Incoming Call, and API Request. For this PHLO, we will use the **API Request** trigger state. 4. Click the **Start** node to open the Configurations tab, and then enter the information to retrieve from the HTTP Request payload. For example, this could be a list of numbers to call. 5. Click **Validate** to save the configurations for the node. 6. From the list of components on the left-hand side, drag and drop the **Initiate Call** component onto the canvas. This will add a Initiate call node onto the canvas. 7. Connect the **Start** node with the **Initiate Call** node, using the **API Request** trigger state. 8. Configure the **Initiate Call** node to select the **From** and **To** numbers from the Start node.**Note:** * Enter two curly brackets to view all available variables. * The values for the **From** and **To** numbers are picked from the HTTP Request Payload. Make sure to clearly define the variables in the Start node. 9. Rename the **Initiate Call** node to **Call\_Customer**. **Note:** You can rename the nodes as per your requirements. We are using specific names in this example to help you relate to the different nodes used in this use case. 10. Click **Validate** to save the configurations for the node. 11. Similarly, create a node for the **IVR Menu** component and connect it to the Initiate Call node using the **Answered** trigger state. 12. Click the **IVR Menu** node to open the Configurations tab. 13. Configure the choices for the IVR Menu from the **Configurations** tab. In this example, we will select **1** and **2** as the allowed choices and enter a message to play to the user. 14. Rename the **IVR Menu** node to **Question\_1**, and then click **Validate** to save the configurations for the node. 15. Similarly, create another **IVR Menu** node and rename it to **Question\_2**. 16. Connect **Question\_2** node to the **Question\_1** node using the **1** and **2** trigger states. 17. Configure the choices for **Question\_2** from the **Configurations** tab. In this example, we will select **1** and **2** as the allowed choices, and enter a message to play to the user. 18. Enter a message in the Speak Text field. The caller will be greeted with this message. **Note:** You can also configure the Language and Voice for the message. 19. Click **Validate** to save the configurations of the node. 20. Create a node for the **Play Audio** component. 21. Rename the node to **Acknowledge\_Participation** using the Configurations tab. 22. Connect **Acknowledge\_Participation** node to the **Question\_2** node using the **1** and **2** trigger states. 23. Configure the **Acknowledge\_Participation** node to speak a message to the customer. 24. Click **Validate** to save the configurations for the node. 25. Next, create a node for **HTTP Request** component and rename it to **Handle\_Callback**. 26. Connect the **Handle\_Callback** node to the **Acknowledge\_Participation** node using the **Prompt Completed** trigger state. 27. Configure the \*\*HTTP Request\_1 \*\*node to post the survey results to a website. 28. In the Params tab, add **answer1** and **answer2** as **Key**. 29. For **answer1**, enter two curly braces and select **Question\_1.digits**. 30. For **answer2**, enter two curly braces and select **Question\_2.digits**. 31. Click **Validate** to save the configurations of the node. 32. After you complete the configurations, click **Save**.You can trigger your PHLO using the PHLO URL to test it out. Triggering the PHLO from your app --------------------------------- Once you have created and configured your PHLO, copy the PHLO Run URL. Integrate a PHLO into your application workflow by making an API request to the PHLO URL with the required payload. #### Code Samples * [Python](#triggering-phlo-api-python) * [Ruby](#triggering-phlo-api-ruby) * [Node.js](#triggering-phlo-api-node) * [PHP](#triggering-phlo-api-php) * [Java](#triggering-phlo-api-java) * [Go](#triggering-phlo-api-go) * [.NET](#triggering-phlo-api-net) * [Curl](#triggering-phlo-api-curl) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 # without payload in request import plivo auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() print str(response) # with payload in request import plivo auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "+12025550000","to" : "+12025551111"} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) print str(response) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 require 'rubygems' require 'plivo' include Plivo AUTH_ID = 'AUTH_ID' AUTH_TOKEN = 'AUTH_TOKEN' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new # without payload in request begin phlo = client.phlo.get('phlo_id') response = phlo.run() puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end # with payload in request begin phlo = client.phlo.get('phlo_id') #parameters set in PHLO - params params = { from: '9999999999', to: '0000000000' } response = phlo.run(params) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = 'auth-id'; var authToken = 'auth-token'; var phloId = 'PHLO_ID'; var phloClient = phlo = null; // without payload in request phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); // with payload in request var payload = { from: '19999999999', to: '18888888888' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 ", ""); // without payload in request $phlo = $client->phlo->get(""); try { $response = $phlo->run(); print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } // with payload in request $phlo = $client->phlo->get(""); try { $response = $phlo->run(["field1" => "value1", "field2" => "value2"]); // These are the fields entered in the PHLO console print_r($response); } catch (PlivoRestException $ex) { print_r($ex); } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import java.io.IOException; // without payload public class Example { private static final String authId = ""; private static final String authToken = ""; private static PlivoClient client = new PlivoClient(authId, authToken); public static void main(String[] args) throws IOException, PlivoRestException { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); PhloUpdateResponse response = Phlo.updater(phloId).payload().run(); } } // with payload public class Example { private static final String authId = ""; private static final String authToken = ""; private static PlivoClient client = new PlivoClient(authId, authToken); public static void main(String[] args) throws IOException, PlivoRestException { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); Map payload = new HashMap<>(); payload.put("phone", "+12025550000"); payload.put("to", "+12025551111"); PhloUpdateResponse response = Phlo.updater(phloId).payload(payload).run(); } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 package main import ( "fmt" "plivo-go" ) // Initialize the following params with corresponding values to trigger resources const authId = "" const authToken = "" const phloId = "phlo_id" // without payload in request func main() { testPhloRunWithoutParams() } func testPhloRunWithoutParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } response, err := phloGet.Run(nil) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) } // with payload in request func main() { testPhloRunWithParams() } func testPhloRunWithParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } //pass corresponding from and to values type params map[string]interface{} response, err := phloGet.Run(params{ "from": "12025550000", "to": "12025551111", }) if err != nil { println(err) } fmt.Printf("Response: %#v\n", response) } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 using System; using Plivo; // without payload namespace test_PHLO_dotnet { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = "phlo_id"; var phlo = phloClient.Phlo.Get(phloID); Console.WriteLine(phlo.Run()); } } } // with payload namespace test_PHLO_dotnet { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = "phlo_id"; var phlo = phloClient.Phlo.Get(phloID); var data = new Dictionary { { "from", "19999999999" }, { "to", "18888888888" } }; Console.WriteLine(phlo.Run(data)); } } } 1 2 3 4 5 curl --request POST \ --user AUTH_ID:AUTH_TOKEN \ --url 'https://phlorunner.plivo.com/v1/account/{auth_id}/phlo/{phlo_id}' \ --header 'Content-Type: application/json' \ --data '{"from": "12025550000","to": "12025551111"}' You can install the server SDKs and setup your development environment by referring to the instructions available in the below links: 1. On the top navigation bar, click **PHLO**. The PHLO page will appear and display your existing PHLOs, if any exist. If this is your first PHLO, then the PHLO page will be empty. 2. Click **CREATE NEW PHLO** to build a new PHLO. 3. From the **CREATE A NEW PHLO** window, select **Build on a blank canvas**, and then click **CREATE PHLO**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. You can choose between the four available trigger states of the Start node; Incoming SMS, Incoming Call, and API Request. For this PHLO, we will use the **API Request** trigger state. 5. Click the **Start** node to open the Configurations tab, and then enter the information to retrieve from the HTTP Request payload. For example, this could be a list of numbers to call. 6. Click **Validate** to save the configurations for the node. 7. From the list of components on the left-hand side, drag and drop the **Initiate Call** component onto the canvas. This will add a Initiate call node onto the canvas. 8. Connect the **Start** node with the **Initiate Call** node, using the **API Request** trigger state. 9. Configure the **Initiate Call** node to select the **From** and **To** numbers from the Start node. **Note:** * Enter two curly brackets to view all available variables. * The values for the **From** and **To** numbers are picked from the HTTP Request Payload. Make sure to clearly define the variables in the Start node. 11. Rename the **Initiate Call** node to **Call\_Customer**. **Note:** You can rename the nodes as per your requirements. We are using specific names in this example to help you relate to the different nodes used in this use case. 13. Click **Validate** to save the configurations for the node. 14. Similarly, create a node for the **IVR Menu** component and connect it to the Initiate Call node using the **Answered** trigger state. 15. Click the **IVR Menu** node to open the Configurations tab. 16. Configure the choices for the IVR Menu from the **Configurations** tab. In this example, we will select **1** and **2** as the allowed choices and enter a message to play to the user. 17. Rename the **IVR Menu** node to **Question\_1**, and then click **Validate** to save the configurations for the node. 18. Similarly, create another **IVR Menu** node and rename it to **Question\_2**. 19. Connect **Question\_2** node to the **Question\_1** node using the **1** and **2** trigger states. 20. Configure the choices for **Question\_2** from the **Configurations** tab. In this example, we will select **1** and **2** as the allowed choices, and enter a message to play to the user. 21. Enter a message in the Speak Text field. The caller will be greeted with this message. **Note:** You can also configure the Language and Voice for the message. 23. Click **Validate** to save the configurations of the node. 24. Create a node for the **Play Audio** component. 25. Rename the node to **Acknowledge\_Participation** using the Configurations tab. 26. Connect **Acknowledge\_Participation** node to the **Question\_2** node using the **1** and **2** trigger states. This will acknowledge the customer’s participation in the survey. 27. Next, create a node for **HTTP Request** component and rename it to **Handle\_Callback**. 28. Connect the **Handle\_Callback** node to the **Acknowledge\_Participation** node using the **Prompt Completed** trigger state. 29. Configure the **HTTP Request\_1** node to post the survey results to a website. 30. In the Params tab, add **answer1** and **answer2** as **Key**. 31. For **answer1**, enter two curly braces and select **Question\_1.digits**. 32. For **answer2**, enter two curly braces and select **Question\_2.digits**. 33. Click **Validate** to save the configurations of the node. 34. After you complete the configurations, click **Save**. You can trigger your PHLO using the PHLO URL to test it out. For more information on using PHLO, see the [PHLO User Guide](/docs/phlo/) . [Server SDKs](/docs/sdk/) [Setup your development environment](/docs/sdk/server/setting-up-dev-environment/) You can get your Auth\_ID and Auth\_token from your [dashboard](https://console.plivo.com/dashboard/) ![AuthID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You can find the PHLO\_ID on the [PHLO Listing](https://console.plivo.com/phlo/list/) page. ![PHLO Listing](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Python Using Django Framework | Plivo Voice * [Python & Flask](/docs/voice/quickstart/python-flask/) * [Python & Django](/docs/voice/quickstart/python-django/) * [Python & FastAPI](/docs/voice/quickstart/python-fastapi/) * [Python & Sanic](/docs/voice/quickstart/python-sanic/) Get Started with Python Using Django Framework ============================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Python Django dev environment ----------------------------------------- You must set up and install Python, Django, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Django and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mydjangoapp $ cd mydjangoapp Install the latest version of the modules using [pip](https://pip.pypa.io/en/latest/) . $ pip3 install django plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using `sudo` with your commands and overwriting dependencies. ### Create a Django project Start a new Django project. $ django-admin startproject VoiceProj This command creates a VoiceProj directory in your projects directory. Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) Change to the project directory and run this command to create a Django application for outbound calls. $ python manage.py startapp outboundcall This command creates an outboundcall directory in your VoiceProj directory. #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Edit `outboundcall/views.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 from django.conf import settings from django.http import HttpResponse from django.views.decorators.csrf import csrf_exempt import plivo @csrf_exempt def outboundcall_response(request): auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() return HttpResponse(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit `outboundcall/views.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 from django.conf import settings from django.http import HttpResponse from django.views.decorators.csrf import csrf_exempt import plivo @csrf_exempt def outboundcall_response(request): auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "","to" : ""} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) return HttpResponse(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Add a route Create a file called outboundcall/urls.py and paste into it this code. 1 2 3 4 5 from django.conf.urls import url from . import views urlpatterns = [\ url(r'^$', views.outboundcall_response, name='outboundcall'),\ ] Add a route for the outboundcall app into the urls.py of your VoiceProj project. Edit VoiceProj/urls.py and add this code. 1 2 3 4 5 6 7 from django.conf.urls import include, url from django.contrib import admin urlpatterns = [\ url(r'^outboundcall/', include('outboundcall.urls')),\ url(r'^admin/', admin.site.urls),\ ] ### Test Run your code. $ python manage.py runserver Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both PHLO and API/XML on our documentation pages. Install Python, Django, and the Plivo Python SDK ------------------------------------------------ You must set up and install Python, Django, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Django and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mydjangoapps $ cd mydjangoapps Install Django and the Plivo Python SDK using [pip](https://pip.pypa.io/en/latest/) . $ pip install django plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using sudo with your commands and overwriting dependencies. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Create a Django project Use django-admin to auto-generate code for a Django project. $ django-admin startproject VoiceProj This command creates a VoiceProj directory in your mydjangoapps directory. ### Create a Django app for outbound calls Change to the new directory and create a Django app for outbound calls. $ python manage.py startapp outboundcall This command creates an outboundcall directory in your VoiceProj directory. Edit `outboundcall/views.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 from django.conf import settings from django.http import HttpResponse from django.views.decorators.csrf import csrf_exempt import plivo @csrf_exempt def outboundcall_response(request): client = plivo.RestClient(settings., settings.) response = client.calls.create( from_=settings., to_='', answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml', answer_method='GET', ) return HttpResponse(response) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.environ to store environment variables and retrieve them when initializing the client. ### Add a route Create the file `outboundcall/urls.py` and paste into it this code. 1 2 3 4 5 from django.conf.urls import url from . import views urlpatterns = [\ url(r'^$', views.outboundcall_response, name='outboundcall'),\ ] Add a route for the outboundcall app into the urls.py of your VoiceProj project. Edit `VoiceProj/urls.py` and paste into it this code. 1 2 3 4 5 6 7 from django.conf.urls import include, url from django.contrib import admin urlpatterns = [\ url(r'^outboundcall/', include('outboundcall.urls')),\ url(r'^admin/', admin.site.urls),\ ] ### Test Run your code. $ python manage.py runserver Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create a Django app to handle incoming calls Change to the VoiceProj directory and create a Django app to handle incoming calls. $ python manage.py startapp receivecall This command creates a receivecall directory in the VoiceProj directory. Edit `receivecall/views.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 from django.conf import settings from django.http import HttpResponse from django.views.decorators.csrf import csrf_exempt from plivo import plivoxml @csrf_exempt def receivecall_response(request): # Generate a Speak XML document with the details of the text to play on the call response = (plivoxml.ResponseElement() .add(plivoxml.SpeakElement('Hello, you just received your first call'))) return HttpResponse(response.to_string(), content_type='text/xml') ### Add a route Create the file `receivecall/urls.py` and paste into it this code. 1 2 3 4 5 from django.conf.urls import url from . import views urlpatterns = [\ url(r'^$', views.receivecall_response, name='receivecall'),\ ] Add a route for the receivecall app into the urls.py of your VoiceProj project. Edit `VoiceProj/urls.py` and paste into it this code. 1 2 3 4 5 6 7 8 from django.conf.urls import include, url from django.contrib import admin urlpatterns = [\ url(r'^outboundcall/', include('outboundcall.urls')),\ url(r'^receivecall/', include('receivecall.urls')),\ url(r'^admin/', admin.site.urls),\ ] Run the code. $ python3 manage.py runserver You should see your basic server app in action at http://localhost:8000/receivecall/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) **Note:** Before starting the service, add ngrok in the allowed hosts list in the settings.py file in your project. ALLOWED_HOSTS = ['.ngrok.io'] Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (8000 in this case): ./ngrok http 8000 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Ngrok CLI](https://docs.plivo.com/assets/posts/images/quickstart/ngrok_cli.png) You can check the app in action at https://6ea358b0f703.ngrok.io/receivecall/ and check the XML response. ![Sample XML response](https://docs.plivo.com/assets/posts/images/quickstart/sample_xml_response.png) ### Create a Plivo application to receive calls Associate the Django app you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call.php/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_phpapp.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create a Django app to forward calls Change to the VoiceProj directory and create a Django app to forward incoming calls. $ python3 manage.py startapp forwardcall This command creates a forwardcall directory in your VoiceProj directory. Edit `forwardcall/views.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 from django.conf import settings from django.http import HttpResponse from django.views.decorators.csrf import csrf_exempt from plivo import plivoxml @csrf_exempt def forwardcall_response(request): # Generate a Dial XML forward the incoming call. response = plivoxml.ResponseElement() response.add( plivoxml.DialElement().add( plivoxml.NumberElement(''))) return HttpResponse(response.to_string(), content_type='text/xml') Replace the destination number placeholder with an actual phone number (for example, 12025551234). ### Add a route Create the file `forwardcall/urls.py` and paste into it this code. 1 2 3 4 5 from django.conf.urls import url from . import views urlpatterns = [\ url(r'^$', views.forwardcall_response, name='forwardcall'),\ ] Add a route for the forwardcall app into the urls.py of your VoiceProj project. Edit `VoiceProj/urls.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 from django.conf.urls import include, url from django.contrib import admin urlpatterns = [\ url(r'^outboundcall/', include('outboundcall.urls')),\ url(r'^receivecall/', include('receivecall.urls')),\ url(r'^forwardcall/', include('forwardcall.urls')),\ url(r'^admin/', admin.site.urls),\ ] If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-python-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Django app you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Reporting | Plivo Developers Reporting ========= The Verify Logs screen on Plivo console helps you analyze and gather information about your outbound and inbound messaging traffic. In addition to the Logs screen, you can get details about your sessions by using Plivo APIs and SDKs programmatically. ### Session logs To view the Session Logs screen, log in to the console and navigate to the Verify > [Logs](https://console.plivo.com/verify/logs/) page. ![](/uploads/screenshot-2023-08-02-at-10-54-19-pm.png) You can view following details for all your sessions for the selected time filters on the Logs screen. 1. Date: The time at which the message was queued in Plivo 2. UUID: Unique identifier for the session 3. Application Alias: Alias for the application used for the session 4. Recipient: The destination number that you are trying to verify 5. Status: The current status of the session; will be in-progress, verified, or expired 6. Attempts: Number of attempts made toward a particular number in a session 7. Country: Country ISO of the destination country 8. Total Charge: Total charge for that session, inclusive of the channel fee ### Filters By default, all messages for your account are displayed on the Logs screen. Use filters to add context to the displayed results. You can filter your results based on: 1. Subaccount 2. Date Range 3. Status 4. Country 5. To Number 6. Application Alias You can use a combination of these filters to narrow your search to relevant messages. **Note:** You can view data up to 90 days old on the Logs screen. Plivo doesn’t retain data for longer than 90 days. ### Export To analyze data, you can download the session details from the console by navigating to the Verify > [Logs](https://console.plivo.com/verify/logs/) page and clicking on **Export**. The exported file will be sent to your account email and will contain these sheets and columns: 1. Sheet 1: Session Logs 1. Time 2. Session UUID 3. Application Alias 4. Auth ID 5. Recipient 6. Status 7. Country 8. Destination Network 9. Total Charge 10. Source IP 11. Attempts 2. Sheet 2: Delivery Attempts 1. Session UUID 2. Channel Name 3. Attempt UUID 4. Time 5. Country 6. Channel Status 7. Channel Charge 8. Destination Network 9. Error Reason Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Call Forwarding Using Node.js | Plivo Docs * [Node](/docs/voice/use-cases/call-forwarding/node/) * [Ruby](/docs/voice/use-cases/call-forwarding/ruby/) * [Python](/docs/voice/use-cases/call-forwarding/python/) * [PHP](/docs/voice/use-cases/call-forwarding/php/) * [.NET](/docs/voice/use-cases/call-forwarding/dotnet/) * [Java](/docs/voice/use-cases/call-forwarding/java/) * [Go](/docs/voice/use-cases/call-forwarding/go/) Call Forwarding Using Node.js ============================= Overview -------- You can use call forwarding to dynamically route incoming calls based on any of several factors. * **Agent availability**: You can place calls in a holding queue and route them to an available agent as soon as one is available. * **Business hours**: You can route calls to an office number during business hours and to a mobile phone or voicemail during non-business hours. * **Time zones**: You can forward calls to agents from different time zones to ensure round-the-clock availability. This guide shows how to forward calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **CREATE NEW PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![Call Forwarding](https://docs.plivo.com/assets/posts/images/phlo/call-forwarding.jpg) Assign the PHLO to a Plivo number --------------------------------- Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) Test ---- You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Here‘s how to use Plivo XML to forward calls. How it works ------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) and a web server and safely expose that server to the internet. Create an Express server to forward incoming calls -------------------------------------------------- Create a file called `forward_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var express = require('express') var app = express() app.post('/forward_call/', function(req, res) { var plivo = require('plivo'); var response = plivo.Response(); var dial = response.addDial(); dial.addNumber(""); // call wll be forwarded to this number res.send(response.toXML()); }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Replace the destination number placeholder with an actual phone number (for example, 12025551234). Save the file and run it. $ node forward_call.js Create a Plivo application to forward calls ------------------------------------------- Associate the Go application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. Assign a Plivo number to your application ----------------------------------------- Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) Test ---- Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Python Using FastAPI Framework| Plivo Voice * [Python & Flask](/docs/voice/quickstart/python-flask/) * [Python & Django](/docs/voice/quickstart/python-django/) * [Python & FastAPI](/docs/voice/quickstart/python-fastapi/) * [Python & Sanic](/docs/voice/quickstart/python-sanic/) Get Started with Python Using FastAPI Framework =============================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Python FastAPI dev environment ------------------------------------------ You must set up and install Python, FastAPI, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install FastAPI and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install the FastAPI framework using [pip](https://pip.pypa.io/en/latest/) . $ pip install fastapi Install an ASGI server for production. [Uvicorn](https://www.uvicorn.org/) and [Hypercorn](https://gitlab.com/pgjones/hypercorn) are two good ones. $ pip install uvicorn Install the Plivo Python SDK. $ pip install plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using `sudo` with your commands and overwriting dependencies. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import plivo from typing import Optional from fastapi import FastAPI app = FastAPI() @app.get("/outbound/") def make_call(): auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() return response Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import plivo from typing import Optional from fastapi import FastAPI app = FastAPI() @app.get("/outbound/") def make_call(): auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "","to" : ""} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) return response Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run your code. $ uvicorn trigger_phlo:app --reload Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both PHLO and API/XML on our documentation pages. Install Python, FastAPI, and the Plivo Python SDK ------------------------------------------------- You must set up and install Python, FastAPI, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install FastAPI and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install the FastAPI framework using [pip](https://pip.pypa.io/en/latest/) . $ pip install fastapi Install an ASGI server for production. [Uvicorn](https://www.uvicorn.org/) and [Hypercorn](https://gitlab.com/pgjones/hypercorn) are two good ones. $ pip install uvicorn Install the Plivo Python SDK. $ pip install plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using sudo with your commands and overwriting dependencies. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a FastAPI server to handle outbound calls Create a file called `main.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import plivo from typing import Optional from fastapi import FastAPI, Response from plivo import plivoxml app = FastAPI() @app.get("/outbound/") def make_call(): client = plivo.RestClient('','') response = client.calls.create( from_='', to_='', answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml', answer_method='GET', ) return response Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.environ to store environment variables and retrieve them when initializing the client. ### Test Save the file and run your code. $ uvicorn main:app --reload Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a FastAPI server to handle incoming calls Edit `main.py` and paste this code into it after the make\_call function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import plivo from typing import Optional from fastapi import FastAPI, Response from plivo import plivoxml app = FastAPI() @app.get("/outbound/") def make_call(): ...... ...... @app.get("/inbound/") def receive_call(): # Generate a Speak XML document with the details of the text to play on the call response = (plivoxml.ResponseElement() .add(plivoxml.SpeakElement('Hello, you just received your first call'))) return Response(response.to_string(), media_type="application/xml") Save the the file and run the code. $ uvicorn main:app --reload You should see your basic server application in action at http://localhost:8000/inbound/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (8000 in this case): ./ngrok http 8000 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Ngrok CLI](https://docs.plivo.com/assets/posts/images/quickstart/ngrok_fastapi.png) You can check the application in action at https://dc141ed7fbb9.ngrok.io/inbound/ and check the XML response. ![Sample XML response](https://docs.plivo.com/assets/posts/images/quickstart/response_fastapi.png) ### Create a Plivo application to receive calls Associate the FastAPI application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call.php/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_app.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a FastAPI server to forward calls Edit `main.py` and paste this code into it after the receive\_call function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 import plivo from typing import Optional from fastapi import FastAPI, Response from plivo import plivoxml app = FastAPI() @app.get("/outbound/") def make_call(): ....... ....... @app.get("/inbound/") def receive_call(): ....... ....... @app.get("/forward/") def forward_call(): response = (plivoxml.ResponseElement() # Generate a Dial XML document to forward the incoming call ​ response = plivoxml.ResponseElement() ​ response.add( ​ plivoxml.DialElement().add( ​ plivoxml.NumberElement(''))) ​ return Response(response.to_string(), media_type="application/xml") Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-python-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Django app you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Callbacks | Plivo Developers Callbacks ========= Using Verify APIs, you can send requests to your users through SMS or voice channels. You can use event-based webhooks — user-defined HTTP callbacks — to track the delivery status of your requests. Plivo sends a status update to a URL you configure as a callback. You can store the information on your server for delivery status analysis. To handle a webhook, you must create a listener (web app) that can accept these HTTP requests from Plivo. ![](/uploads/screenshot-2023-08-02-at-7-19-23-pm.png) ### Setting up webhooks **Code** * [Curl](#setting-up-webhooks-curl) 1 2 3 4 5 6 7 8 9 10 curl -i --user auth_id:auth_token \ -H "Content-Type: application/json" \ -d '{ "app_uuid":"", "recipient": "", "url":"https://.com/sms_status/", "channel":"sms", "method":"POST" }' \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/ **Notes:** * Replace the auth\_id and auth\_token placeholders with your authentication credentials, which you can find on the Overview screen of the [Plivo console](https://console.plivo.com/dashboard/) . * Replace the app\_uuid placeholder with the application that you created and recipient with the phone number you’ll be sending your OTP to. recipient should be in [E.164 format](https://en.wikipedia.org/wiki/E.164) . * Replace channel placeholder with the channel that you wish to use - either sms or voice * Replace https://.com/sms\_status/ with the webhook URL you’ve set up. ### Handle callbacks in your web app To handle callbacks in your app, your endpoint should capture HTTP requests and respond to them. When Plivo sends the HTTP request callbacks to the 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. You can store the callback data to your database. **Note:** Plivo automatically retries webhooks three times if an HTTP 200 status code is not returned: * First at 60 seconds after the original attempt. * Second at 120 seconds after the first retry attempt. * Third at 240 seconds after the second retry attempt. ### Test and validate Let’s look at an example. Typically, you would include a URL that points to your web app, but we’ll use a URL from [RequestBin](https://requestbin.com/) , a service that lets you collect, analyze, and debug HTTP requests, so we can check the callbacks. * Create a new bin in RequestBin. * Replace the “url” placeholder with the URL of the new bin. * Run the code that appears above. You should receive the SMS message on the phone number defined in the destination field, and see callback requests in RequestBin similar to the screenshots below for callback events such as queued, sent, and delivered. ### Callback format Plivo sends the following fields to your application: * SessionUUID: Unique identifier for you sessions * SessionStatus: Status of the session; either in-progress, verified, or expired * RequestTime: Time when this attempt was made * Recipient: Number of the recipient * ChannelErrorCode: Error code for the channel * Channel: Channel used * AttemptUUID: Unique identifier for each attempt * AttemptSequence: Sequence number of this attempt in a session * ChannelStatus: Status of your attempt, which can take different values depending on the channel * SMS: sent, delivered, failed, undelivered * Voice: in-progress, completed, no-answer ### 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 include X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2, and X-Plivo-Signature-V2-Nonce HTTP headers. You can use them to validate that a request is from Plivo, as we discuss in our [signature validation guide](/docs/verify/concepts/signature-validation/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Conference Calling with a PIN Using Node.js| Plivo Docs * [Node](/docs/voice/use-cases/conference-with-pin/node/) * [Ruby](/docs/voice/use-cases/conference-with-pin/ruby/) * [Python](/docs/voice/use-cases/conference-with-pin/python/) * [PHP](/docs/voice/use-cases/conference-with-pin/php/) * [.NET](/docs/voice/use-cases/conference-with-pin/dotnet/) * [Java](/docs/voice/use-cases/conference-with-pin/java/) * [Go](/docs/voice/use-cases/conference-with-pin/go/) Conference Calling with a PIN Using Node.js =========================================== Overview -------- This guide shows how to create and configure conference calls with a PIN to let multiple people securely connect to a single call. Only participants who have a specified passcode can enter the conference call. You can make conference calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a workflow to implement conference calling with a PIN with a few clicks on the PHLO canvas. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **CREATE NEW PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Conference Bridge** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Conference Bridge** node. * In the Configuration tab at the right of the canvas, under Conference Type, tick Protected, then enter a participant PIN and a moderator PIN for the conference. All participants must enter the participant PIN to connect to the conference. The moderator must use the moderator PIN to start the conference. * You can also add an announcement message to greet callers, and configure the hold music. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![Conference with Pin](https://docs.plivo.com/assets/posts/images/phlo/conferencewithpin.jpg) Assign the PHLO to a Plivo number --------------------------------- Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo.png) Test ---- You can now call to your Plivo phone number and see how callers are added to a conference call that requires PIN validation. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Here’s how to receive a call on a Plivo number and add the caller to a conference call named “demo” after the caller enters a valid PIN. How it works ------------ ![Conference with PIN Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/pin.png) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) and a web server and safely expose that server to the internet. Create an Express server to implement a conference call with PIN ---------------------------------------------------------------- Create a file called `conference_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 var plivo = require('plivo'); var express = require('express'); var bodyParser = require('body-parser'); var app = express(); app.use(bodyParser.urlencoded({extended: true})); app.set('port', (process.env.PORT || 5000)); // Message that Plivo reads when the caller dials in var WelcomeMessage = "Welcome to the demo. Press 1234 to join the conference"; // Message that Plivo reads when the caller does nothing var NoinputMessage = "Sorry, I didn't catch that. Please hang up and try again"; // Message that Plivo reads when the caller enters an invalid number. var WronginputMessage = "Sorry, that's an invalid PIN"; app.post('/conference/', function(request, response) { var r = plivo.Response(); var getinput_action_url, params, get_input; getinput_action_url = request.protocol + '://' + request.headers.host + '/conference/firstbranch/'; params = { 'action': getinput_action_url, 'method': 'POST', 'inputType': 'dtmf', 'digitEndTimeout': '5', 'numDigits': '5', 'redirect': 'true', }; get_input = r.addGetInput(params); get_input.addSpeak(WelcomeMessage); r.addSpeak(NoinputMessage); console.log(r.toXML()); response.set({'Content-Type': 'text/xml'}); response.send(r.toXML()); }); app.post('/conference/firstbranch/', function(request, response) { var r = plivo.Response(); var getinput_action_url, params, get_input; var digit = request.query.Digits; console.log(digit); if (digit === '1234') { var params = { 'startConferenceOnEnter': "true", 'endConferenceOnExit': "true" }; var conference_name = "demo"; r.addConference(conference_name, params); } else { r.addSpeak(WronginputMessage); } console.log(r.toXML()); response.set({'Content-Type': 'text/xml'}); response.send(r.toXML()); }); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Save the file and run it. $ node conference_call.js You should see your basic server application in action at http://localhost:3000/conference/. Create a Plivo application for the conference call -------------------------------------------------- Associate the Express application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Conference Call`. Enter the server URL you want to use (for example `https://.com/conference/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Conference Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/create_conferenceapp.jpg) Assign a Plivo number to your application ----------------------------------------- Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Conference Call` (the name we gave the application). Click **Update Number** to save. ![Assign Conference Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_conferencecall.jpg) Test ---- Make a call to your Plivo number. You should be prompted for a PIN, then placed into a conference after PIN validation. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Python Using Sanic Framework| Plivo Voice * [Python & Flask](/docs/voice/quickstart/python-flask/) * [Python & Django](/docs/voice/quickstart/python-django/) * [Python & FastAPI](/docs/voice/quickstart/python-fastapi/) * [Python & Sanic](/docs/voice/quickstart/python-sanic/) Get Started with Python Using Sanic Framework ============================================= Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Python Sanic dev environment ---------------------------------------- You must set up and install Python, Sanic, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Sanic and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install the latest version of the modules using [pip](https://pip.pypa.io/en/latest/) . $ pip3 install sanic $ pip3 install plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using `sudo` with your commands and overwriting dependencies. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import plivo from sanic import Sanic from sanic.response import text app = Sanic('Plivo Voice App') @app.route('/outbound', methods=['POST', 'GET']) async def make_call(request): auth_id = '' auth_token = '' phlo_id = '' phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run() return text(response, content_type="text/json") if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `trigger_phlo.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 import plivo from sanic import Sanic from sanic.response import text app = Sanic('Plivo Voice App') @app.route('/outbound', methods=['POST', 'GET']) async def make_call(request): auth_id = '' auth_token = '' phlo_id = '' payload = {"from" : "","to" : ""} phlo_client = plivo.phlo.RestClient(auth_id=auth_id, auth_token=auth_token) phlo = phlo_client.phlo.get(phlo_id) response = phlo.run(**payload) return text(response, content_type="text/json") if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ python trigger_phlo.py Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both PHLO and API/XML on our documentation pages. Install Python, Sanic, and the Plivo Python SDK ----------------------------------------------- You must set up and install Python, Sanic, and Plivo’s Python SDK before you make your first call. ### Install Python [Download and install Python](https://www.python.org/downloads/) from its official site. ### Install Sanic and the Plivo Python SDK Create a projects directory and change into it. $ mkdir mypythonapp $ cd mypythonapp Install the Sanic framework and the Plivo Python SDK using [pip](https://pip.pypa.io/en/latest/) . $ pip install sanic plivo We recommend that you use [virtualenv](https://virtualenv.pypa.io/en/stable/) to manage and segregate your Python environments, instead of using sudo with your commands and overwriting dependencies. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a Sanic server to handle outbound calls Create a file called `main.py` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 import plivo from plivo import plivoxml from sanic import Sanic from sanic.response import text app = Sanic('Plivo Voice App') @app.route('/outbound', methods=['POST', 'GET']) async def make_call(request): client = plivo.RestClient('','') response = client.calls.create( from_='', to_='', answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml', answer_method='GET', ) print(response) return text(response, content_type="text/json") if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.environ to store environment variables and retrieve them when initializing the client. ### Test Save the file and run your code. $ python main.py Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sanic server to handle incoming calls Edit `main.py` and paste this code into it after the make\_call function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 import plivo from plivo import plivoxml from sanic import Sanic from sanic.response import text app = Sanic('Plivo Voice App') @app.route('/outbound', methods=['POST', 'GET']) async def make_call(request): ....... ....... @app.route('/inbound', methods=['POST', 'GET']) async def receive_call(request): # Generate a Speak XML document with the details of the text to play on the call response = (plivoxml.ResponseElement() .add(plivoxml.SpeakElement('Hello, you just received your first call'))) return text(response.to_string(), content_type="text/xml") if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) Save the file and run the code. $ python main.py You should see your basic server application in action at http://localhost:8000/inbound/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (8000 in this case): ./ngrok http 8000 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Ngrok CLI](https://docs.plivo.com/assets/posts/images/quickstart/ngrok_fastapi.png) You can check the application in action at https://dc141ed7fbb9.ngrok.io/inbound/ and check the XML response. ![Sample XML response](https://docs.plivo.com/assets/posts/images/quickstart/response_fastapi.png) ### Create a Plivo application to receive calls Associate the Sanic application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call.php/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_app.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sanic server to forward calls Edit `main.py` and paste this code into it after the receive\_call function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 import plivo from plivo import plivoxml from sanic import Sanic from sanic.response import text app = Sanic('Plivo Voice App') @app.route('/outbound', methods=['POST', 'GET']) async def make_call(request): ....... ....... @app.route('/inbound', methods=['POST', 'GET']) async def receive_call(request): ....... ....... @app.route('/forward', methods=['POST', 'GET']) async def forward_call(request): response = plivoxml.ResponseElement() response.add( plivoxml.DialElement().add( plivoxml.NumberElement(''))) return text(response.to_string(), content_type="text/xml") if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-python-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Django app you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/python/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Fraud Control | Plivo Developers Fraud Control ============= One way to block fraudulent messaging traffic is to restrict the set of countries your account can send messages to. Plivo uses geo permissions to help curb SMS and voice fraud. We’ll block (and not charge for) any messages or calls sent to countries to which sending is not allowed. Each Verify request is made from an application that’s mapped to a subaccount. You can access your applications and the subaccounts they’re mapped to on the [Plivo console](https://console.plivo.com/verify/applications/) . ### Messaging Plivo recommends that all customers use our new Fraud Shield to help curb the risk of SMS fraud, such as [SMS pumping](https://www.plivo.com/blog/sms-pumping/) and [account token takeover](https://support.plivo.com/hc/en-us/articles/4406366772633-What-should-I-do-if-I-suspect-my-account-has-been-compromised-) . Fraud Shield’s Geo Permissions feature allows you to control the countries to which your SMS traffic is sent. For the countries that you wish to send messages to, Fraud Thresholds can be enabled. It’s a limit of how many messages can be set per hour to the countries that you have approved. This control allows you to take corrective action if the threshold is breached. We’ll block (and not charge for) any messages that are intended for countries not included in your destination list. ![Fraud Control-Messaging](https://docs.plivo.com/assets/dist/images/fraudshield_final-3.gif) Visit the [Fraud Shield documentation](https://www.plivo.com/docs/messaging/concepts/fraud-shield/) to learn more and start configuring your settings. ### Voice Plivo can protect your account from fraud by restricting the set of countries your account can call. If, for example, you intend to place calls to numbers in North America only, you can disable call routes to all other continents. Similarly, if you’re running an inbound call center, or your use case doesn’t involve outbound calling to PSTN numbers, you can block outbound routes to all countries as a precautionary measure. To manage geo permissions, navigate to Voice > [Geo Permissions](https://console.plivo.com/voice/settings/geo-permissions/) on the Plivo console. ![](/uploads/screenshot-2023-08-02-at-10-47-19-pm.png) Here you’ll see a list of all countries. You can filter the list by selecting specific geographic regions or countries. Geo permission configurations are applied immediately to all calls initiated via Plivo APIs. ### Calling premium rate numbers Premium rate numbers are a special case of voice calling. These numbers cost callers more than normal numbers. Part of that charge is paid to the service provider, which puts premium rate numbers at high risk of being exploited via traffic pumping, a type of telecom fraud in which bad actors artificially inflate traffic to their premium rate numbers. When done across countries, this type of toll fraud is known as International Revenue Share Fraud (ISRF). Most businesses never need to call premium rate numbers, so by default Plivo blocks calls to all phone numbers with high-risk prefixes as a way to prevent unwanted charges. Plivo has identified thousands of premium rate and high-risk prefixes. You can export a list of these prefixes from the Voice > [Geo Permissions](https://console.plivo.com/voice/settings/geo-permissions/) screen on the High-Risk Permissions tab. Plivo regularly updates this list based on factors such as the rates associated with the premium numbers, call patterns, and third-party trends. If you have a legitimate need to make calls to premium rate or high-risk numbers, you can request activation of high-risk permissions for your account or a particular subaccount by contacting our support team and providing them with details of your use case. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Pinless Conference using Node.js| Plivo Docs * [Node](/docs/voice/use-cases/call-conference/node/) * [Ruby](/docs/voice/use-cases/call-conference/ruby/) * [Python](/docs/voice/use-cases/call-conference/python/) * [PHP](/docs/voice/use-cases/call-conference/php/) * [.NET](/docs/voice/use-cases/call-conference/dotnet/) * [Java](/docs/voice/use-cases/call-conference/java/) * [Go](/docs/voice/use-cases/call-conference/go/) PINless Conference Calls Using Node.js ====================================== Overview -------- This guide shows how to create and configure conference calling, which lets you connect multiple people to one call at the same time. You can implement PINless conference calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a workflow to implement conference calling with a few clicks on the PHLO canvas. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **CREATE NEW PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Conference Bridge** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Conference Bridge** node. * In the Configuration tab at the right of the canvas, enter a Conference ID for your conference. You can also add an announcement message to greet callers, and configure the hold music. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![Conference without Pin](https://docs.plivo.com/assets/posts/images/phlo/conferencewithoutpin.jpg) Assign the PHLO to a Plivo number --------------------------------- Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo.png) Test ---- You can now call to your Plivo phone number and see how callers are added to a conference call. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Here’s how to receive a call on a Plivo number and add the caller to a conference call named “demo” using the [Conference XML](/docs/voice/xml/conference/) element. How it works ------------ ![PINless Conference Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/pinless-conference.png) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) and a web server and safely expose that server to the internet. Create an Express server to implement a conference call ------------------------------------------------------- Create a file called `conference_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 var express = require('express') var app = express() app.post('/conference_call/', function(req, res) { var plivo = require('plivo'); var response = plivo.Response(); var speak_body = "You will now be placed into the demo conference"; response.addSpeak(speak_body); var params = { 'startConferenceOnEnter': "true", 'endConferenceOnExit': "true" }; var conference_name = "demo"; response.addConference(conference_name, params); res.send(response.toXML()); }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Save the file and run it. $ node conference_call.js You should see your basic server application in action at http://localhost:3000/conference\_call/. Create a Plivo application for the conference call -------------------------------------------------- Associate the Node.js application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Conference Call`. Enter the server URL you want to use (for example `https://.com/conference_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Conference Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/create_conferenceapp.jpg) Assign a Plivo number to your application ----------------------------------------- Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Conference Call` (the name we gave the application). Click **Update Number** to save. ![Assign Conference Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_conferencecall.jpg) Test ---- Make a call to your Plivo number. You should be placed into a conference. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Ruby Using Sinatra Framework | Plivo Voice * [Ruby Sinatra](/docs/voice/quickstart/ruby-sinatra/) * [Ruby on Rails](/docs/voice/quickstart/ruby-rails/) Get Started with Ruby Using Sinatra Framework ============================================= Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up Your Ruby dev environment -------------------------------- You must set up and install Ruby, Sinatra, and Plivo’s Ruby SDK before you make your first call. ### Install Ruby On macOS or Linux, see if you already have Ruby installed by running ruby --version in a terminal window. If you don’t have it or want to use a more recent version, you can install it using [Homebrew](https://www.ruby-lang.org/en/documentation/installation/#homebrew) . On Windows, use [RubyInstaller](https://rubyinstaller.org/) . ### Install Sinatra $ gem install sinatra ### Install the Plivo Ruby SDK Create a projects directory and change into it. $ mkdir myrubyapp $ cd myrubyapp Edit your application’s Gemfile and add the line gem 'plivo', '>= 4.24.0' Then run $ bundle Or install it yourself. $ gem install plivo Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `trigger_phlo.rb` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 require 'rubygems' require 'plivo' include Plivo AUTH_ID = '' AUTH_TOKEN = '' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new begin phlo = client.phlo.get('') response = phlo.run() puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `trigger_phlo.rb` and into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 require 'rubygems' require 'plivo' include Plivo AUTH_ID = '' AUTH_TOKEN = '' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new begin phlo = client.phlo.get('') params = { from: '', to: '' } response = phlo.run(params) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ ruby trigger_phlo.rb Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/ruby/) with code for both PHLO and API/XML on our documentation pages. Install Ruby, Sinatra, and the Plivo Ruby SDK --------------------------------------------- You must set up and install Ruby, Sinatra, and Plivo’s Ruby SDK before you make your first call. ### Install Ruby [Download and install Ruby](https://www.ruby-lang.org/en/documentation/installation/) from its official site. ### Install Sinatra $ gem install sinatra ### Install the Plivo Ruby SDK Create a projects directory and change into it. $ mkdir myrubyapp $ cd myrubyapp Edit the Gemfile and add this line. gem 'plivo', '~> 4.24.0' Then install the Plivo Ruby gem into the bundle. $ bundle install Or install it yourself. $ gem install plivo Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Set up a Sinatra server to handle outbound calls Create a file called `Makecall.rb` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 require 'rubygems' require 'plivo' include Plivo include Plivo::Exceptions api = RestClient.new("","") begin response = api.calls.create( '', [''], 'https://s3.amazonaws.com/static.plivo.com/answer.xml' ) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use ENV to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. $ ruby Makecall.rb Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sinatra server to handle incoming calls Create a file called `receive_call.rb` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 require "sinatra" require 'plivo' include Plivo::XML get "/receive_call/" do response = Response.new speak_body = 'Hello, you just received your first call' response.addSpeak(speak_body) xml = PlivoXML.new(response) content_type "application/xml" return xml.to_s() end Save the file and run it. $ ruby receive_call.rb You should see your basic server application in action at http://localhost:4567/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): $ ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the Rails application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_app.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sinatra server to forward calls Create a file called `forward_call.rb` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 require 'rubygems' require 'plivo' include Plivo::XML include Plivo::Exceptions begin response = Response.new dial = response.addDial() dial.addNumber("") xml = PlivoXML.new(response) content_type "application/xml" return xml.to_s() end Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-ruby-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Ruby application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/ruby/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Ruby on Rails Framework | Plivo Voice * [Ruby Sinatra](/docs/voice/quickstart/ruby-sinatra/) * [Ruby on Rails](/docs/voice/quickstart/ruby-rails/) Get Started with Ruby on Rails Framework ======================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up Your Ruby dev environment -------------------------------- You must set up and install Ruby, Sinatra, and Plivo’s Ruby SDK before you make your first call. ### Install Ruby On macOS or Linux, see if you already have Ruby installed by running ruby --version in a terminal window. If you don’t have it or want to use a more recent version, you can install it using [Homebrew](https://www.ruby-lang.org/en/documentation/installation/#homebrew) . On Windows, use [RubyInstaller](https://rubyinstaller.org/) . ### Install Sinatra $ gem install sinatra ### Install the Plivo Ruby SDK Create a projects directory and change into it. $ mkdir myrubyapp $ cd myrubyapp Edit your application’s Gemfile and add the line gem 'plivo', '>= 4.24.0' Then run $ bundle Or install it yourself. $ gem install plivo Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `trigger_phlo.rb` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 require 'rubygems' require 'plivo' include Plivo AUTH_ID = '' AUTH_TOKEN = '' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new begin phlo = client.phlo.get('') response = phlo.run() puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `trigger_phlo.rb` and into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 require 'rubygems' require 'plivo' include Plivo AUTH_ID = '' AUTH_TOKEN = '' client = Phlo.new(AUTH_ID, AUTH_TOKEN) # if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables # then initialize client as: # client = Phlo.new begin phlo = client.phlo.get('') params = { from: '', to: '' } response = phlo.run(params) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ ruby trigger_phlo.rb Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/ruby/) with code for both PHLO and API/XML on our documentation pages. Install Ruby, Rails, and the Plivo Ruby SDK ------------------------------------------- You must set up and install Ruby, Rails, and Plivo’s Ruby SDK before you make your first call. ### Install Ruby [Download and install Ruby](https://www.ruby-lang.org/en/documentation/installation/) from its official site. ### Install Rails $ gem install rails ### Create a Rails project Create a Rails project to autogenerate code in the Ruby on Rails folder structure. $ rails new plivotest This command creates a `plivotest` directory with the necessary folders and files for development. ### Install the Plivo Ruby SDK Edit the Gemfile and add this line. gem 'plivo', '~> 4.24.0' Then install the Plivo Ruby gem into the bundle. $ bundle install Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Create a Rails controller to handle outbound calls Run this command in the project directory. $ rails generate controller Plivo voice This command generates a controller named plivo\_controller in the app/controllers/ directory and a respective view in the app/views/plivo directory. We can delete the view as we don’t need it. $ rm app/views/plivo/voice.html.erb Edit app/controllers/plivo\_controller.rb and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 include Plivo include Plivo::Exceptions class PlivoController < ApplicationController def outbound api = RestClient.new("","") response = api.calls.create( '', [''], 'https://s3.amazonaws.com/static.plivo.com/answer.xml' ) puts response render json: response.to_s end end Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use ENV to store environment variables and retrieve them when initializing the client. ### Add a route Edit config/routes.rb and change the line get 'plivo/voice' to get 'plivo/outbound' ### Test Run your code. $ rails server Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Rails server to handle incoming calls Edit app/controllers/plivo\_controller.rb and paste this code into the PlivoController class after the outbound function. 1 2 3 4 5 6 7 8 def inbound response = Response.new speak_body = 'Hello, you just received your first call' response.addSpeak(speak_body) xml = Plivo::PlivoXML.new(response) render xml: xml.to_xml end ### Add a route Edit config/routes.rb and and add this line after the outbound route. get 'plivo/inbound' Run your code. $ rails server You should see your basic server application in action at http://localhost:3000/plivo/inbound/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) **Note:** Before starting the service, add ngrok in the config.hosts list in the config/environments/development.rb file in your project. You will see _Blocked host_ errors if you fail to do this. # Whitelist ngrok domain config.hosts << /[a-z0-9]+\.ngrok\.io/ Run ngrok on the command line, specifying the port that hosts the application on which you want to receive calls (3000 in this case): $ ./ngrok http 3000 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![ngrok CLI](https://docs.plivo.com/assets/posts/images/voice/quickstart/ngrok-rails.png) You can check the application in action at https://021bf9953e9f.ngrok.io/plivo/inbound/ and check the XML response. ![Sample XML](https://docs.plivo.com/assets/posts/images/voice/quickstart/xml-rails.png) ### Create a Plivo application to receive calls Associate the Rails application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/quickstart/create_receivecall_app.png) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive_call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/quickstart/assign_receivecall_app.png) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Rails server to forward calls Edit app/controllers/plivo\_controller.rb and paste this code into the PlivoController class after the inbound function we added earlier. 1 2 3 4 5 6 7 8 9 10 def forward response = Response.new dial = response.addDial() dest_number = "" dial.addNumber(dest_number) xml = PlivoXML.new(response) puts xml.to_xml render xml: xml.to_xml end Replace the destination number placeholder with an actual phone number (for example, 12025551234). ### Add a route Edit config/routes.rb and and add this line after the inbound route. get 'plivo/forward' If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-ruby-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Ruby application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/ruby/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Translation support | Plivo Developers Translation support =================== Plivo supports your effort to reach customers in the language of their choice. [Plivo support](https://support.plivo.com/hc/en-us) can help you translate and configure your application to translate messages automatically. Once you configure translations for your SMS templates, you can [create a verify session](https://www.plivo.com/docs/verify/api/session/create-a-session/) by passing the “locale” preference as a parameter. “locale” refers to a string that combines a language code (in small caps) in ISO 639-1 format and a region code (in large caps) in ISO 3166-1 format (optional). For example: en\_US, en, en\_GB, es, fr\_FR etc. If you pass a locale for which translation is not available or if you pass an incorrect locale value, the default locale (en) will be chosen. To use specific SMS content for a certain geography, we recommend creating a specific locale and using it when you create verify sessions for this region. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Validating Requests and Responses | Plivo Developers Validating Requests and Responses ================================= All requests made by Plivo to your server URLs contain `X-Plivo-Signature-V2`, `X-Plivo-Signature-Ma-V2`, and `X-Plivo-Signature-V2-Nonce` HTTP headers. To validate a request and to verify that the request to your server originated from Plivo, you must generate a signature at your end and check that it matches with the `X-Plivo-Signature-V2` or `X-Plivo-Signature-Ma-V2` parameter in the HTTP header. You can use either `X-Plivo-Signature-V2` or `X-Plivo-Signature-Ma-V2` to validate a signature. * **X-Plivo-Signature-V2** is generated using the Auth Token of the associated account or subaccount. To validate using the **X-Plivo-Signature-V2** request header, you must generate a signature at your end using the same account or subaccount. * **X-Plivo-Signature-Ma-V2** is always generated using the Auth Token of the main account. To validate using the **X-Plivo-Signature-Ma-V2** request header, you must generate the signature using the main account. Generating and validating the signature --------------------------------------- You can generate the signature by calculating the keyed hash message authentication code (HMAC) with these parameters: * Key — Your Plivo Auth Token * Message — Base URI appended with X-Plivo-Signature-V2-Nonce. For example, if the base URI is https://.com/answer/ and X-Plivo-Signature-V2-Nonce is 05429567804466091622, the message will be https://.com/answer/05429567804466091622. * Hashing Function — SHA256 Code ---- * [Python](#signature-validation-sms-python) * [Ruby](#signature-validation-sms-ruby) * [Node.js](#signature-validation-sms-node) * [PHP](#signature-validation-sms-php) * [Java](#signature-validation-sms-java) * [Go](#signature-validation-sms-go) * [.NET](#signature-validation-sms-net) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 from flask import Flask, request, make_response, url_for import plivo app = Flask(__name__) @app.route('/receive_sms/', methods =['GET','POST']) def signature(): signature = request.headers.get('X-Plivo-Signature-V2') nonce = request.headers.get('X-Plivo-Signature-V2-Nonce') uri = url_for('signature', _external=True) auth_token = "" output = plivo.utils.validate_signature(uri,nonce,signature,auth_token) print(output) from_number = request.values.get('From') # Sender's phone numer to_number = request.values.get('To') # Receiver's phone number - Plivo number text = request.values.get('Text') # The text which was received print('Message received - From: %s, To: %s, Text: %s' %(from_number, to_number, text)) return "Text received" if __name__ == "__main__": app.run(host='0.0.0.0', debug=True) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 require 'sinatra' require 'rubygems' require 'plivo' include Plivo require 'uri' get '/receive_sms/' do auth_token = "" signature = request.env["HTTP_X_PLIVO_SIGNATURE_V2"] nonce = request.env["HTTP_X_PLIVO_SIGNATURE_V2_NONCE"] url = request.url uri = (url.split("?"))[0] output = Plivo::Utils.valid_signature?(uri,nonce,signature,auth_token) puts output from_number = params[:From]# The phone number of the person who sent the SMS to_number = params[:To]# Your Plivo number that will receive the SMS text = params[:Text]# The text which was received on your Plivo number puts "Message received from #{from_number} : #{ text }" end 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 var plivo = require('plivo'); var express = require('express'); var app = express(); app.set('port', (process.env.PORT || 5000)); app.use(express.static(__dirname + '/public')); app.use(express.urlencoded({ extended: true })) app.all('/receive_sms/', function(req, res) { var auth_token = (''); var signature = req.get('X-Plivo-Signature-V2'); var nonce = req.get('X-Plivo-Signature-V2-Nonce'); var fullUrl = req.protocol + '://' + req.get('host') + req.originalUrl; var from_number = req.body.From;// Sender's phone number var to_number = req.body.To;// Receiver's phone number - Plivo number var text = req.body.Text;// The text which was received var output = plivo.validateSignature(fullUrl, nonce, signature, auth_token) console.log(output); console.log ('From : ' + from_number + ' To : ' + to_number + ' Text : ' + text); }); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 "; $signature = $_SERVER["HTTP_X_PLIVO_SIGNATURE_V2"]; $nonce = $_SERVER["HTTP_X_PLIVO_SIGNATURE_V2_NONCE"]; $url = 'http' . (isset($_SERVER['HTTPS']) ? 's' : '') . '://' . "{$_SERVER['HTTP_HOST']}{$_SERVER['REQUEST_URI']}"; $uri = explode('?',$url); $uri1 = $uri[0]; $SVUtil = new signatureValidation(); $output = $SVUtil->validateSignature($uri1,$nonce,$signature,$auth_token); var_export($output); $from_number = $_REQUEST["From"];// Sender's phone numer $to_number = $_REQUEST["To"];// Receiver's phone number - Plivo number $text = $_REQUEST["Text"];// The SMS text message which was received echo("Message received from $from_number : $text"); ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 import java.io.IOException; import java.net.URLDecoder; import java.util.Iterator; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import com.plivo.api.util.Utils; import java.io.IOException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import org.eclipse.jetty.server.Server; import org.eclipse.jetty.servlet.ServletContextHandler; import org.eclipse.jetty.servlet.ServletHolder; import com.plivo.api.util.*; import com.plivo.api.exceptions.*; public class validateSignature extends HttpServlet { private static final long serialVersionUID = 1L; @Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String auth_token = ""; String signature = req.getHeader("X-Plivo-Signature-V2"); String nonce = req.getHeader("X-Plivo-Signature-V2-Nonce"); String url = req.getRequestURL().toString(); try { Boolean isValid = Utils.validateSignature(url, nonce, signature, auth_token); System.out.println("Valid : " + isValid); } catch (Exception e) { e.printStackTrace(); } String from_number = req.getParameter("From"); String to_number = req.getParameter("To"); String text = req.getParameter("Text"); System.out.println("From : " + from_number + " To : " + to_number + " Text : " + text); } public static void main(String[] args) throws Exception { String port = System.getenv("PORT"); if(port==null) port ="8080"; Server server = new Server(Integer.valueOf(port)); ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS); context.setContextPath("/"); server.setHandler(context); context.addServlet(new ServletHolder(new validateSignature()),"/receive_sms"); server.start(); server.join(); } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 package main import ( "fmt" "net/http" "github.com/plivo/plivo-go/v7" ) func handler(w http.ResponseWriter, r *http.Request) { originalurl := "https://" + r.Host + r.URL.Path authToken := "" signature := r.Header.Get("X-Plivo-Signature-V2") nonce := r.Header.Get("X-Plivo-Signature-V2-Nonce") fromnumber := r.FormValue("From") tonumber := r.FormValue("To") text := r.FormValue("Text") response := plivo.ValidateSignatureV2( originalurl, nonce, signature, authToken, ) fmt.Printf("Response: %#v\n", response) print("Message Received - ", fromnumber, " ", tonumber, " ", text) } func main() { http.HandleFunc("/receive_sms/", handler) http.ListenAndServe(":8080", nil) } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 using System; using System.Collections.Generic; using System.Diagnostics; using RestSharp; using Plivo.Utilities; using Nancy; namespace validateSignature { public class Program : NancyModule { public Program() { Get["/receive_sms/"] = x => { IEnumerable signature = Request.Headers["X-Plivo-Signature-V2"]; String[] sign = (String[])signature; String actualsignature = sign[0]; IEnumerable nonce = Request.Headers["X-Plivo-Signature-V2-Nonce"]; String[] key = (String[])nonce; String actualnonce = key[0]; String auth_token = ""; String url = Request.Url.SiteBase + Request.Url.Path; bool valid = Plivo.Utilities.XPlivoSignatureV2.VerifySignature(url, actualnonce, actualsignature, auth_token); Debug.WriteLine("Valid : " + valid); String from_number = Request.Query["From"]; String to_number = Request.Query["To"]; String text = Request.Query["Text"]; Debug.WriteLine("From : {0}, To : {1}, Text : {2}", from_number, to_number, text); Console.ReadLine(); return "OK"; }; } } } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started Sending SMS Notifications Using Node.js | Plivo Docs * [Node](/docs/messaging/use-cases/sms-notification/node/) * [Ruby](/docs/messaging/use-cases/sms-notification/ruby/) * [Python](/docs/messaging/use-cases/sms-notification/python/) * [PHP](/docs/messaging/use-cases/sms-notification/php/) * [.NET](/docs/messaging/use-cases/sms-notification/dotnet/) * [Java](/docs/messaging/use-cases/sms-notification/java/) * [Go](/docs/messaging/use-cases/sms-notification/go/) Send SMS Notifications Using Node.js ==================================== Overview -------- This guide shows how to send an SMS notification or alert to any phone number. You can send SMS notifications and alerts either by using our PHLO visual workflow builder or our APIs. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_api.svg)Using API](#api) * * * You can create a PHLO to send SMS notifications with a few clicks on the PHLO canvas and trigger it with a few lines of code. How it works ------------ Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time triggering a PHLO with Node.js, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-phlo/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left-hand side, drag and drop the **Send Message** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Send Message** node. * In the Configuration pane at the right of the canvas, configure the **Send Message** node with a sender ID in the **From** field. Enter the destination number you wish to send a message to in the **To** field. Put your message in the **Text** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![SMS Notification](https://docs.plivo.com/assets/posts/images/phlo/sms-notification.jpg) Your PHLO is now ready to test. Trigger the PHLO ---------------- You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) ### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms_static.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . ### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms_access_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { From: '', To: '', } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). Test ---- Save the file and run it. node TriggerPhlo.js Here’s how to use Plivo APIs to send SMS notifications. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To send messages to the United States and Canada, you must have a Plivo phone number that supports SMS; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-messaging/) . Create the send SMS application ------------------------------- Create a file called `send_sms.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); (function main() { 'use strict'; var client = new plivo.Client("", ""); client.messages.create( { src: "", dst: "", text: "Appointment reminder: 12:00 noon tomorrow. Please reply to this message if you need to make a change" } ).then(function (response) { console.log(response); }); })(); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). In countries other than the US and Canada you can use a [sender ID](/docs/messaging/concepts/sender-id-usage/) for the message source. You must have a Plivo phone number to send messages to the US or Canada; you can buy a Plivo number from Phone Numbers > [Buy Numbers](https://console.plivo.com/phone-numbers/search/) on the Plivo console or via the [Numbers API](https://www.plivo.com/docs/numbers/api/phone-number/#buy-a-phone-number) . **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and fetch them when initializing the client. Test ---- Save the file and run it. Your application triggers an outbound SMS API request, and Plivo delivers your message to the destination number you specified. node send_sms.js Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with SMS Surveys Using Node.js | Plivo Docs * [Node](/docs/messaging/use-cases/sms-survey/node/) * [Ruby](/docs/messaging/use-cases/sms-survey/ruby/) * [Python](/docs/messaging/use-cases/sms-survey/python/) * [PHP](/docs/messaging/use-cases/sms-survey/php/) * [.NET](/docs/messaging/use-cases/sms-survey/dotnet/) * [Java](/docs/messaging/use-cases/sms-survey/java/) * [Go](/docs/messaging/use-cases/sms-survey/go/) Conduct SMS Surveys Using Node.js ================================= Overview -------- This guide shows how to conduct an SMS survey. Surveys can help businesses with market research. Using SMS for surveys lets organizations process input quickly and efficiently. You can conduct SMS surveys either by using our PHLO visual workflow builder or our APIs. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_api.svg)Using API](#api) * * * You can create and deploy a PHLO to conduct an SMS survey with a few clicks on the PHLO canvas and trigger it with a few lines of code. How it works ------------ Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. If this is your first time triggering a PHLO with Node.js, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-phlo/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * If you plan to use a dynamic payload — passing values through parameters when you trigger the PHLO from your application — click on the **Start** node to open the Configuration pane. Under **API Request**, enter key names for the variables you want use in your payload — **From**, **To**, and **Message** fields. * Once you’ve configured the node, click **Validate** to save the configuration. * From the list of components on the left-hand side, drag and drop the **Send Message** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Send Message** node. * In the Configuration pane at the right of the canvas, configure the **Send Message** node with a sender ID in the **From** field. Enter the destination numbers you wish to send a message to in the **To** field. Put your message in the **Text** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * From the list of components on the left-hand side, drag and drop the **Branch** component onto the canvas. * Draw a line to connect the **Start** node’s **Incoming Message** trigger state to the **Branch** node. * In the Configuration pane at the right of the canvas, configure the **Branch** node. Rename the node to **Handle\_Reply**. For **Variable to compare**, enter two curly braces to view all available variables, then select **Start.message.msg**. * Click the pencil icon and name the first condition **Satisfied**. Leave the **Operation** “is equal to” and enter a value of **1**. * Add a second condition. Name it **Not Satisfied** and enter a value of **2**. * Once you’ve configured the node, click **Validate** to save the configuration. * Drag two **Send Message** nodes onto the canvas. Draw lines to connect them to the **Handle\_Reply** node using the **Satisfied** and **Not Satisfied** trigger states. * In the Configuration pane for each of the **Send Message** nodes, specify the **From** and **To** keys you configured in the Start node. Enter two curly brackets to display a list of all available variables. In the **Message** field, you can enter a static message, or combine static text with a variable that includes dynamic text if you specified the variable as a key in the **Start** node configuration pane. * Rename the nodes **Reply\_Satisfied** and **Reply\_NotSatisfied**. * Once you’ve configured the nodes, click **Validate** to save their configurations. * From the list of components on the left-hand side, drag and drop the **HTTP Request** component onto the canvas. Draw four lines to connect the **Sent** and **Failed** trigger states of both the **Reply\_Satisfied** and **Reply\_NotSatisfied** nodes to the HTTP Request node. * In the Configuration pane for the **HTTP Request** node, rename the node to **Handle\_Callback**. Enter URL to make the request to. The default method used is **GET**, but you can click on the box to choose **POST**, **PUT**, or **DELETE** instead. Specify Headers, Auth, Params, and Body values on their respective tabs as necessary. * Once you’ve configured the node, click **Validate** to save the configuration. After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this: ![SMS Survey](https://docs.plivo.com/assets/posts/images/phlo/sms-survey.png) Your PHLO is now ready to test. Trigger the PHLO ---------------- You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) ### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms_static.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . ### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO … ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms_payload.png) … and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/sms/quickstart/phlo/send_sms_access_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { From: '', To: '', } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). Test ---- Save the file and run it. node TriggerPhlo.js Here’s how to use Plivo APIs to create surveys using SMS text messages — sending questions and collecting answers. How it works ------------ ![Outbound-SMS Flow](https://docs.plivo.com/assets/posts/images/sms/usecase-guides/advanced/sms-survey/sms-survey.jpg) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming messages, you must have a Plivo phone number that supports SMS; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-messaging/) . Create the survey application ----------------------------- Create a file called `survey.js` and paste the below code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 const express = require('express') const plivo = require('plivo') const app = express() const port = 3000 var bodyParser = require('body-parser') app.use( bodyParser.json() ); // to support JSON-encoded bodies app.use(bodyParser.urlencoded({ // to support URL-encoded bodies extended: true })); app.post('/send_survey/', function(req, res) { let client = new plivo.Client('', ''); client.messages.create({ src: '', dst: '', text: 'Did you find out all the information you needed? Please reply "Yes" or "No"' }).then(function(message_created) { res.status(200).send(message_created) }); }); app.post('/survey_response/', function(req, res) { let from_number = req.body.From; let to_number = req.body.To; let text = req.body.Text; console.log('Message received - From: ' + from_number + ', To: ' + to_number + ', Text: ' + text); let plivoxml = plivo.Response(); let params = { 'src': to_number, 'dst': from_number, }; if (text.toLowerCase() == "yes") { message_body = "Thank you for your feedback"; } else if (text.toLowerCase() == "no") { message_body = "We apologize for the inconvenience. A representative will contact you to assist you"; } else { message_body = `Response received was "${text}", which is invalid. Please reply with either "Yes" or "No"`; } plivoxml.addMessage(message_body, params); res.contentType('text/xml'); res.end(plivoxml.toXML()).status(200); }); app.listen(port, () => { console.log(`Example app listening on port ${port}`) }) Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). In countries other than the US and Canada you can use a [sender ID](/docs/messaging/concepts/sender-id-usage/) for the message source. You must have a Plivo phone number to send messages to the US or Canada; you can buy a Plivo number from Phone Numbers > [Buy Numbers](https://console.plivo.com/phone-numbers/search/) on the Plivo console or via the [Numbers API](https://www.plivo.com/docs/numbers/api/phone-number/#buy-a-phone-number) . **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and fetch them when initializing the client. Test ---- Save the file and run it. $ node survey.js Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Phone System IVR using Node.js| Plivo Docs * [Node](/docs/voice/use-cases/ivr/node/) * [Ruby](/docs/voice/use-cases/ivr/ruby/) * [Python](/docs/voice/use-cases/ivr/python/) * [PHP](/docs/voice/use-cases/ivr/php/) * [.NET](/docs/voice/use-cases/ivr/dotnet/) * [Java](/docs/voice/use-cases/ivr/java/) * [Go](/docs/voice/use-cases/ivr/go/) Phone system IVR Using Node.js ============================== Overview -------- Interactive voice response (IVR) systems let incoming callers access information and find contacts via a menu of prerecorded messages, without having to speak to an agent, and let you automate polling via outgoing calls. Callers and call recipients can respond to prompts via Touch-Tone keypad presses or speech recognition. IVR systems can handle larger call volumes than operators and reduce costs associated with customer service. Common IVR use cases include: * **Auto-attendant**: You can replace a receptionist with an IVR system that routes calls to agents during business hours and accepts voicemail when no one is available. * **Call center**: You can route calls coming in to call centers to the appropriate representatives based on user input. * **Surveys, polling, and voting**: You can implement IVR in outbound calls to collect customer satisfaction scores or conduct political polling. * **Appointment reminders**: You can send automated reminders to customers before their scheduled visits to help avoid missed appointments and facilitate rescheduling. * **Lead assignment and lead routing**: For inbound sales calls, you can set up an IVR menu with a set of qualifying questions to discover a customer’s interests, then redirect their call to a representative based on their responses. This guide shows how to build an IVR menu system on the Plivo platform, either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a workflow to implement an IVR system with a few clicks on the PHLO canvas. Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **CREATE NEW PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * Click the **Start** node to open the Configuration tab, then enter information that other nodes can retrieve in the API Request section — in this case, the From and optionally To numbers for the IVR system. * From the list of components on the left side, drag and drop the **IVR Menu** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **IVR Menu** node. * In the Configuration tab at the right of the canvas, configure the choices for the IVR menu. For this example, select **1** and **2** as allowed choices. Enter a message to play to the user in the Speak Text box. * Once you’ve configured the node, save the configuration by clicking **Validate**. Do the same for each node as you go along. * Drag and drop two instances of the **Call Forward** component onto the canvas. Rename them **Connect\_to\_Support** and **Connect\_to\_Sales**. Draw lines to connect the **IVR Menu** node‘s **1** and **2** trigger states to the new nodes. * Configure each **Call Forward** node to select the From number using a variable. PHLO will get the number from the key/value pairs set in the Start node. Enter two curly brackets to view all available variables, and choose the appropriate one. For the To number, either enter a fixed number directly into the To field, or use a variable that you configured in the Start node. * Drag and drop two instances of the **Play Audio** component onto the canvas. Rename the two nodes **No\_Input\_Prompt** and **Invalid\_Input\_Prompt** and configure each to speak a fixed message for callers to hear when they enter no input or invalid input. Draw lines from the **IVR Menu** node‘s No Input and Wrong Input trigger states to the respective nodes, then draw lines from the **Prompt Completed** trigger states of the new nodes back to the IVR Menu node, to give callers another chance to enter a menu choice. * Give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![Phone System IVR](https://docs.plivo.com/assets/posts/images/phlo/phonesystem-ivr.jpg) Assign the PHLO to a Plivo number --------------------------------- Once you‘ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo.png) Test ---- You can now call your Plivo phone number and see how the IVR system works. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Here‘s how to implement an IVR system using XML. How it works ------------ ![Phone System IVR Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/ivr.png) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) and a web server and safely expose that server to the internet. Create an Express server to implement IVR ----------------------------------------- Create a file called `ivr.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 var plivo = require('plivo'); var express = require('express'); var bodyParser = require('body-parser'); var app = express(); app.use(bodyParser.urlencoded({extended: true})); app.set('port', (process.env.PORT || 5000)); // Message that Plivo reads when the caller dials in var IvrMessage1 = "Welcome to the demo. Press 1 to contact sales. Press 2 to contact support"; // Message that Plivo reads when the caller does nothing var NoinputMessage = "Sorry, I didn't catch that. Please hang up and try again"; // Message that Plivo reads when the caller enters an invalid number var WronginputMessage = "Sorry, that's not a valid entry"; // Sales Phone number var salesPhoneNumber = "+15671234567" // Support Phone number var supportPhoneNumber = "+15671234578" app.post('/ivr/', function(request, response) { var r = plivo.Response(); var getinput_action_url, params, get_input; getinput_action_url = request.protocol + '://' + request.headers.host + '/ivr/firstbranch/'; params = { 'action': getinput_action_url, 'method': 'POST', 'inputType': 'dtmf', 'digitEndTimeout': '5', 'redirect': 'true', }; get_input = r.addGetInput(params); get_input.addSpeak(IvrMessage1); r.addSpeak(NoinputMessage); console.log(r.toXML()); response.set({'Content-Type': 'text/xml'}); response.send(r.toXML()); }); app.post('/ivr/firstbranch/', function(request, response) { var r = plivo.Response(); var digit = request.body.Digits; console.log(digit); if (digit === '1') { var dial = r.addDial(); dial.addNumber(salesPhoneNumber); } else if (digit === '2') { var dial = r.addDial(); dial.addNumber(supportPhoneNumber); } else { r.addSpeak(WronginputMessage); } console.log(r.toXML()); response.set({'Content-Type': 'text/xml'}); response.send(r.toXML()); }); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Save the file and run it. node ivr.js You should see your basic server application in action at http://localhost:3000/ivr/. [Set up ngrok](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/#ngrok-setup) to expose your local server to the internet. Create a Plivo application -------------------------- Associate the Express server you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Phone IVR`. Enter the server URL you want to use (for example `https://.com/ivr/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Plivo Create Application Phone IVR](https://docs.plivo.com/assets/posts/images/voice/quickstart/create_phoneIVR.jpg) Assign a Plivo number to your application ----------------------------------------- Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Phone IVR` (the name we gave the application). Click **Update Number** to save. ![Assign Application Phone IVR](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_phoneIVR.jpg) Test ---- Make a call to your Plivo phone number and see how the IVR application works. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Authentication | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Authentication** ------------------ All requests to the Verify API are authenticated with **BasicAuth** using your Auth ID and Auth Token, which you can find on the Overview page of the Plivo [console](https://console.plivo.com/dashboard/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with .NET Framework | Plivo Voice * [.NET Core](/docs/voice/quickstart/dotnet-core/) * [.NET Framework](/docs/voice/quickstart/dotnet-framework/) Get Started with .NET Framework =============================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your .NET Framework dev environment ------------------------------------------ You must set up and install .NET Framework 4.6 or higher and Plivo’s .NET SDK before you make your first call. You can check whether you already have .NET Framework installed under macOS or Linux and what version is installed by running the command dotnet --version in a terminal window. Under Windows there are [several ways to check](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#determine-which-net-implementation-and-version-an-app-is-running-on) . If you don’t have it or need a more current version, [download and install it](https://dotnet.microsoft.com/download) . ### Install the Plivo .NET SDK using Visual Studio Create a new project in Visual Studio. ![Create New Project](https://docs.plivo.com/assets/posts/images/voice/quickstart/step1.jpg) Choose Console Application as the template for the new project. ![Choose Template](https://docs.plivo.com/assets/posts/images/voice/quickstart/step2.jpg) Install the Plivo NuGet package. ![Manage Nuget packages](https://docs.plivo.com/assets/posts/images/voice/quickstart/step4.jpg) ![Select Plivo Nuget package](https://docs.plivo.com/assets/posts/images/voice/quickstart/step5.jpg) Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code In Visual Studio, in the CS project, edit the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 using System; using Plivo; namespace test_PHLO { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = ""; var phlo = phloClient.Phlo.Get(phloID); Console.WriteLine(phlo.Run()); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code In Visual Studio, in the CS project, open the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 using System; using System.Collections.Generic; using Plivo; namespace test_PHLO { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = ""; var phlo = phloClient.Phlo.Get(phloID); var data = new Dictionary { { "from", "" }, { "to", "" } }; Console.WriteLine(phlo.Run(data)); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run the code from the Visual Studio IDE. Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an Incoming call ------------------------ You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/dotnet/) with code for both PHLO and API/XML on our documentation pages. Install .NET Framework and the Plivo .NET SDK --------------------------------------------- You must set up and install .NET Framework 4.6 or higher and Plivo’s .NET SDK before you make your first call. ### Install .NET Framework You can check whether you already have .NET Framework installed under macOS or Linux and what version is installed by running the command dotnet --version in a terminal window. Under Windows there are [several ways to check](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#determine-which-net-implementation-and-version-an-app-is-running-on) . If you don’t have it or need a more current version, [download and install it](https://dotnet.microsoft.com/download) . ### Install the Plivo .NET SDK using Visual Studio Create a new project in Visual Studio. ![Create New Project](https://docs.plivo.com/assets/posts/images/voice/quickstart/step1.jpg) Choose Console Application as the template for the new project. ![Choose Template](https://docs.plivo.com/assets/posts/images/voice/quickstart/step2.jpg) Install the Plivo NuGet package. ![Manage Nuget packages](https://docs.plivo.com/assets/posts/images/voice/quickstart/step4.jpg) ![Select Plivo Nuget package](https://docs.plivo.com/assets/posts/images/voice/quickstart/step5.jpg) Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code In Visual Studio, in the CS project, open the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 using System; using System.Collections.Generic; using Plivo; namespace testplivo { class Program { static void Main(string[] args) { var api = new PlivoApi("",""); var response = api.Call.Create( to: new List { "" }, from: "", answerMethod: "GET", answerUrl: "https://s3.amazonaws.com/static.plivo.com/answer.xml" ); Console.WriteLine(response); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use the [Environment.SetEnvironmentVariable](https://docs.microsoft.com/en-us/dotnet/api/system.environment.setenvironmentvariable?view=netcore-3.1) method to store environment variables and [Environment.GetEnvironmentVariable](https://docs.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable?view=netcore-3.1) to fetch them when initializing the client. ### Test Save the file and run it. ![Make outbound call](https://docs.plivo.com/assets/posts/images/voice/quickstart/build_app.jpg) Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. To be able to host answer and callback URLs and to be able to provide valid XML and accept notifications on these URLs, you need to host a web server. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create an MVC project In Visual Studio, create a new project. Use the template for Web Application (Model-View-Controller). ![Create a MVC app](https://docs.plivo.com/assets/posts/images/voice/quickstart/create_mvcapp.jpg) Give the project a name — we used `Receivecall`. ![Configure the MVC app](https://docs.plivo.com/assets/posts/images/voice/quickstart/configure_mvcapp.jpg) Navigate to the Controllers directory in the Receivecall project. Create a controller named ReceivecallController.cs and paste into it this code. ![Install Plivo Nuget Package](https://docs.plivo.com/assets/posts/images/voice/quickstart/create_controller.jpg) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 using System; using Plivo.XML; using System.Collections.Generic; using Microsoft.AspNetCore.Mvc; namespace Receivecall { public class ReceivecallController : Controller { public IActionResult Index() { Plivo.XML.Response resp = new Plivo.XML.Response(); resp.AddSpeak("Hello, you just received your first call", new Dictionary() { { "loop", "3" } }); var output = resp.ToString(); Console.WriteLine(output); return this.Content(output, "text/xml"); } } } Before you start the application, edit Properties/launchSettings.json and set applicationUrl. "applicationUrl": "http://localhost:5000/" Run the project and you should see your basic server application in action at http://localhost:5000/receivecall/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) You can check app in action at https://3b3e783f.ngrok.io/receivecall and check the XML response. ![XML Document](https://docs.plivo.com/assets/posts/images/voice/quickstart/ngrok_coremvc.jpg) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create an MVC controller to forward incoming calls Create a controller called `ForwardcallController.cs` in the Controllers directory and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 using System; using Plivo.XML; using System.Collections.Generic; using Microsoft.AspNetCore.Mvc; namespace Receivecall { public class ForwardcallController : Controller { public IActionResult Index() { Plivo.XML.Response resp = new Plivo.XML.Response(); Plivo.XML.Dial dial = new Plivo.XML.Dial(new Dictionary() { }); dial.AddNumber("", new Dictionary() { }); resp.Add(dial); var output = resp.ToString(); Console.WriteLine(output); return this.Content(output, "text/xml"); } } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-dotnet-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the .NET application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/dotnet/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # API Request | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) API Request =========== Plivo exposes a list of REST APIs to perform various actions. You can use these APIs in combination with [Verify applications](/docs/verify/overview/) . `POST` `https://api.plivo.com/v1/` Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Node.js Using Express | Plivo Voice * [Node.js & Express](/docs/voice/quickstart/node-expressjs/) * [Node.js & NestJS](/docs/voice/quickstart/node-nestjs/) * [Node.js & Sails](/docs/voice/quickstart/node-sails/) * [Node.js & serverless](/docs/voice/quickstart/node-serverless/) Get Started with Node.js Using Express ====================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up Your Node.js and Express dev environment ----------------------------------------------- You must set up and install Node.js and Plivo’s Node.js SDK before you make your first call. You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . #### Install the Plivo Node.js package Create a projects directory and change into it. $ mkdir mynodeapp $ cd mynodeapp Install the Plivo Node.js SDK using [npm](https://www.npmjs.com/package/plivo) . $ npm install plivo Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 var express = require('express') var app = express() app.post('/trigger_phlo/', function(req, res) { var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function(result) { console.log('Phlo run result', result); }).catch(function(err) { console.error('Phlo run failed', err); }) }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 var express = require('express') var app = express() app.post('/trigger_phlo/', function(req, res) { var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { from: '', to: '' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ node TriggerPhlo.js Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both PHLO and API/XML on our documentation pages. Install Node.js, Express, and the Plivo Node.js SDK --------------------------------------------------- You must set up and install Node.js, Express, and Plivo’s Node.js SDK before you make your first call. ### Install Node.js You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . ### Install Express and the Plivo Node.js SDK Create a projects directory and change into it. $ mkdir mynodeapp $ cd mynodeapp Install Express and the Plivo Node.js SDK using [npm](https://www.npmjs.com/package/plivo) . $ npm install express plivo Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Create a file called `Makecall.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 var plivo = require('plivo'); (function main() { 'use strict'; var client = new plivo.Client("",""); client.calls.create( "", "", "https://s3.amazonaws.com/static.plivo.com/answer.xml", { answerMethod: "GET", }, ).then(function (response) { console.log(response); }, function (err) { console.error(err); }); })(); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. $ node Makecall.js Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up an Express server to handle incoming calls Create a file named `receive_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var plivo = require('plivo'); var express = require('express'); var app = express(); app.all('/receive_call/', function(req, res) { var response = plivo.Response(); var speak_body = "Hello, you just received your first call"; response.addSpeak(speak_body); res.writeHead(200, {'Content-Type': 'text/xml'}); res.end(response.toXML()); }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Save the file and run it. $ node receive_call.js You should see your basic server application for inbound calls in action at http://localhost:5000/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up an Express application to forward calls Create a file called `forward_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var express = require('express') var app = express() app.post('/forward_call/', function(req, res) { var plivo = require('plivo'); var response = plivo.Response(); var dial = response.addDial(); dial.addNumber(""); res.send(response.toXML()); }) app.set('port', (process.env.PORT || 5000)); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-node-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Express application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with .NET Core | Plivo Voice * [.NET Core](/docs/voice/quickstart/dotnet-core/) * [.NET Framework](/docs/voice/quickstart/dotnet-framework/) Get Started with .NET Core ========================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your .NET Core dev environment ------------------------------------- You must set up and install .NET Core and Plivo’s .NET SDK before you make your first call. ### Install .NET Core You can check whether you already have .NET Framework installed under macOS or Linux and what version is installed by running the command dotnet --version in a terminal window. Under Windows there are [several ways to check](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#determine-which-net-implementation-and-version-an-app-is-running-on) . If you don’t have it or need a more current version, [download and install it](https://dotnet.microsoft.com/download) . ### Install the Plivo .NET SDK Create a projects directory and change into it. $ mkdir mydotnetcoreapp $ cd mydotnetcoreapp Install the Plivo SDK using the [.NET CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) . $ dotnet new console $ dotnet add package Plivo Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code In Visual Studio, in the CS project, open the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 using System; using Plivo; namespace test_PHLO { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = ""; var phlo = phloClient.Phlo.Get(phloID); Console.WriteLine(phlo.Run()); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code In Visual Studio, in the CS project, open the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 using System; using System.Collections.Generic; using Plivo; namespace test_PHLO { class Program { public static void Main(string[] args) { var phloClient = new PhloApi("", ""); var phloID = ""; var phlo = phloClient.Phlo.Get(phloID); var data = new Dictionary { { "from", "" }, { "to", "" } }; Console.WriteLine(phlo.Run(data)); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ dotnet run Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/dotnet/) with code for both PHLO and API/XML on our documentation pages. Install .NET Core and the Plivo .NET SDK ---------------------------------------- You must set up and install .NET Core and Plivo’s .NET SDK before you make your first call. ### Install .NET Core You can check whether you already have .NET Core installed under macOS or Linux and what version is installed by running the command dotnet --version in a terminal window. Under Windows there are [several ways to check](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#determine-which-net-implementation-and-version-an-app-is-running-on) . If you don’t have it or need a more current version, [download and install it](https://dotnet.microsoft.com/download) . ### Install the Plivo .NET SDK Create a projects directory and change into it. $ mkdir mydotnetcoreapp $ cd mydotnetcoreapp Install the Plivo SDK using the [.NET CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) . $ dotnet new console $ dotnet add package Plivo Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code In the CS project, open the file `Program.cs` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 using System; using System.Collections.Generic; using Plivo; namespace PlivoExamples { internal class Program { public static void Main(string[] args) { var api = new PlivoApi("",""); var response = api.Call.Create( to:new List{""}, from:"", answerMethod:"GET", answerUrl:"https://s3.amazonaws.com/static.plivo.com/answer.xml" ); Console.WriteLine(response); } } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use the [Environment.SetEnvironmentVariable](https://docs.microsoft.com/en-us/dotnet/api/system.environment.setenvironmentvariable?view=netcore-3.1) method to store environment variables and [Environment.GetEnvironmentVariable](https://docs.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable?view=netcore-3.1) to fetch them when initializing the client. ### Test Save the file and run it. $ dotnet run Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. To be able to host answer and callback URLs and to be able to provide valid XML and accept notifications on these URLs, you need to host a web server. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create an MVC project In the .NET Core projects directory, create a new [MVC](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new#web-options) project. $ dotnet new mvc --no-https ### Create an MVC controller to handle incoming calls Navigate to the Controllers subdirectory, create a controller named `ReceivecallController.cs`, and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 using System; using Plivo.XML; using System.Collections.Generic; using Microsoft.AspNetCore.Mvc; namespace receivecallapp.Controllers { public class ReceivecallController : Controller { public IActionResult Index() { Plivo.XML.Response resp = new Plivo.XML.Response(); resp.AddSpeak("Hello, you just received your first call", new Dictionary() { { "loop", "3" } }); var output = resp.ToString(); Console.WriteLine(output); return this.Content(output, "text/xml"); } } } Before you start the application, edit Properties/launchSettings.json and set applicationUrl. "applicationUrl": "http://localhost:5000/" Start the local server. $ dotnet run You should see your basic server application in action at http://localhost:5000/receivecall/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) You can check the app in action at https://3b3e783f.ngrok.io/receivecall and check the XML response. ![XML Document](https://docs.plivo.com/assets/posts/images/voice/quickstart/ngrok_coremvc.jpg) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create an MVC controller to forward calls Create a controller called `ForwardcallController.cs` in the Controllers directory and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 using System; using Plivo.XML; using System.Collections.Generic; using Microsoft.AspNetCore.Mvc; namespace receivecallapp.Controllers { public class ForwardcallController : Controller { public IActionResult Index() { Plivo.XML.Response resp = new Plivo.XML.Response(); Plivo.XML.Dial dial = new Plivo.XML.Dial(new Dictionary() { }); dial.AddNumber("", new Dictionary() { }); resp.Add(dial); var output = resp.ToString(); Console.WriteLine(output); return this.Content(output, "text/xml"); } } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-dotnet-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the .NET application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/dotnet/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Content-Type | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Content-Type** ---------------- Plivo only accepts input of the type application/json. All **POST** requests arguments must be passed as json with the Content-Type set as application/json. All **GET** and **DELETE** request arguments must be passed in the query string. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get started with Voicemail using Node.js| Plivo Docs * [Node](/docs/voice/use-cases/voicemail/node/) * [Ruby](/docs/voice/use-cases/voicemail/ruby/) * [Python](/docs/voice/use-cases/voicemail/python/) * [PHP](/docs/voice/use-cases/voicemail/php/) * [.NET](/docs/voice/use-cases/voicemail/dotnet/) * [Java](/docs/voice/use-cases/voicemail/java/) * [Go](/docs/voice/use-cases/voicemail/go/) Voicemail Using Node.js ======================= Overview -------- You can use voicemail to capture a caller’s message if a call recipient is unavailable. This guide shows how to set up voicemail, either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * You can create and deploy a workflow to implement voicemail with a few clicks on the PHLO canvas. ![Voicemail call flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/phlo/voicemail.png) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . Create the PHLO --------------- To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. * Click **CREATE NEW PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * Click the **Start** node to open the Configuration tab, then enter **from** and **to** as keys in the API Request section. To keep the PHLO dynamic, don‘t enter values for the variables. * Once you’ve configured the node, save the configuration by clicking **Validate**. Do the same for each node as you go along. * From the list of components on the left side, drag and drop the **Record Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. In its Configuration tab, give the node a descriptive name, such as Voicemail\_Message, and enter text for a message you want to play to callers. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Record Audio** node. * Once a message is recorded, send the URL of the recording to a responsible party. To do that, drag and drop the **Send Message** component into the canvas, and rename it **Send\_Recording\_URL**. * In its Configuration tab, enter variables for the From and To fields. Enter two curly brackets to view all available variables, and choose the appropriate ones. PHLO will get the number from the key/value pairs set in the Start node. In the Message field, enter a message that provides context for the voicemail recipient. The message can be static or dynamic or a combination of the two. * Give the PHLO a name by clicking in the upper left, then click **Save**. Your complete PHLO should look like this. ![Voicemail](https://docs.plivo.com/assets/posts/images/phlo/voicemail.png) Assign the PHLO to a Plivo number --------------------------------- Once you‘ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo.png) Test ---- You can now call your Plivo phone number and see how the voicemail PHLO works. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Here’s how to implement voicemail using XML. How it works ------------ ![Voicemail Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/voicemail.png) Prerequisites ------------- To get started, you need a Plivo account — [sign up](https://console.plivo.com/accounts/register/) with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . If this is your first time using Plivo APIs, follow our instructions to [set up a Node.js development environment](/docs/sdk/server/set-up-node-dev-environment-api-xml-voice/) and a web server and safely expose that server to the internet. Create an Express server to implement voicemail ----------------------------------------------- Create a file called `voicemail.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 var plivo = require('plivo'); var express = require('express'); var bodyParser = require('body-parser'); var app = express(); app.use(bodyParser.urlencoded({extended: true})); app.set('port', (process.env.PORT || 5000)); app.post('/voicemail/', function(request, response) { var r = plivo.Response(); var params; params = { 'action': "https://.com/get_recording/", 'finishOnKey': "*", 'maxLength': "20" }; r.addRecord(params); var second_speak_body = "Recording not received"; r.addSpeak(second_speak_body); console.log(r.toXML()); response.set({'Content-Type': 'text/xml'}); response.send(r.toXML()); }); app.listen(app.get('port'), function() { console.log('Node app is running on port', app.get('port')); }); Save the file and run it. $ node voicemail.js You should see your basic server application in action at http://localhost:3000/voicemail/. Create a Plivo application for voicemail ---------------------------------------- Associate the Express server you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Voicemail`. Enter the server URL you want to use (for example `https://.com/voicemail/`) in the `Answer URL` field and set the method to `GET`. Click **Create Application** to save your application. ![Plivo Create Application Voicemail](https://docs.plivo.com/assets/posts/images/voice/quickstart/create-voicemail.png) Assign a Plivo number to your application ----------------------------------------- Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Voicemail` (the name we gave the application). Click **Update Number** to save. ![Assign Voicemail Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign-voicemail.png) Test ---- Make a call to your Plivo number and leave yourself a voicemail message. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Timeouts and Proxies | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Timeouts and Proxies** ------------------------ The server SDKs provide for specifying timeouts and proxy settings to be used while making API requests. In the code window, select the programming language of your choice and click on the latest version to see how to specify these settings. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Overview | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) Overview ======== The Plivo Voice API uses HTTP verbs and standard HTTP status codes to make it easier for you to integrate communications into your code. To secure your requests to our servers, we serve our API calls over HTTPS. **Note**: The current version of the API is `v1`, and the [server SDKs](/docs/sdk/server/) are versioned as `latest` and `legacy`. #### API Endpoint `POST` `https://api.plivo.com/{version}/` Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Overview | Plivo XML Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) Plivo XML Overview ================== Your application must use Plivo XML to control a call or message synchronously. You can combine XML elements in different ways to perform complex actions, such as: * Playing music while a caller is on hold * Reading specified text to a caller * Requesting numeric input * Dialing and connecting to another number Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Node.js using Sails Framework | Plivo Voice * [Node.js & Express](/docs/voice/quickstart/node-expressjs/) * [Node.js & NestJS](/docs/voice/quickstart/node-nestjs/) * [Node.js & Sails](/docs/voice/quickstart/node-sails/) * [Node.js & serverless](/docs/voice/quickstart/node-serverless/) Get Started with Node.js using Sails Framework ============================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Install Node.js, Sails, and the Plivo Node.js SDK ------------------------------------------------- You must set up and install Node.js, Sails, and Plivo’s Node SDK before you make your first call. ### Install Node.js You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . ### Install Sails Install Sails using [npm](https://www.npmjs.com/package/sails) . $ npm install sails -g Choose the npm package manager when prompted for which package manager to use. Create a new (empty) Sails project and change to the project directory. $ sails new $ cd ### Install the Plivo Node.js SDK Install the Plivo Node.js SDK using [npm](https://www.npmjs.com/package/plivo) . $ npm install plivo Once you’ve set up your development environment, you can start sending and receiving messages using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Edit api/controllers/HelloController.js and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 var plivo = require('plivo'); module.exports = { trigger_phlo: function(req, res) { var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function(result) { return res.status(200).json(result); }).catch(function(err) { console.error('Phlo run failed', err); }) }, }; Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Edit config/route.js to set the route. 'POST /trigger_phlo' : 'HelloController.trigger_phlo', #### Test Save the file and run it. $ sails lift #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit api/controllers/HelloController.js and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 var plivo = require('plivo'); module.exports = { trigger_phlo: function(req, res) { var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; const payload = { From: '', To: '', }; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function(result) { return res.status(200).json(result); }).catch(function(err) { console.error('Phlo run failed', err); }) }, }; Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). Edit config/route.js to set the route. 'POST /trigger_phlo' : 'HelloController.trigger_phlo', #### Test Save the file and run it. $ sails lift Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both PHLO and API/XML on our documentation pages. Install Node.js, Sails, and the Plivo Node.js SDK ------------------------------------------------- You must set up and install Node.js, Sails, and Plivo’s Node SDK before making your first voice call. ### Install Node.js You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . ### Install Sails Install Sails using [npm](https://www.npmjs.com/package/sails) . $ npm install sails -g Choose the npm package manager when prompted for which package manager to use. Create a new (empty) Sails project and change to the project directory. $ sails new $ cd ### Install the Plivo Node.js SDK Install the Plivo Node.js SDK using [npm](https://www.npmjs.com/package/plivo) . $ npm install plivo Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Create a Sails controller Create a new controller called “hello.” sails generate controller hello Edit api/controllers/HelloController.js and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 var plivo = require('plivo'); module.exports = { make_call: function(req, res) { var client = new plivo.Client("", ""); client.calls.create({ "", "", "https://s3.amazonaws.com/static.plivo.com/answer.xml", { answerMethod: "GET", }, }).then(function(response) { return res.status(200).json(response); }); }, }; Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and retrieve them when initializing the client. Edit config/route.js to set the route. 'POST /make_call' : 'HelloController.make_call', ### Test Save the file and run it. $ sails lift You should see your basic server application in action at http://localhost:1337/make\_call/. Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sails server to handle incoming calls Edit api/controllers/HelloController.js and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 var plivo = require('plivo'); module.exports = { receive_call: function(req, res) { var response = plivo.Response(); var speak_body = "Hello, you just received your first call"; response.addSpeak(speak_body); res.setHeader("Content-type", "text/xml"); return res.status(200).send(response.toXML()); }, }; Edit config->route.js to set the route. 'POST /receive_call' : 'HelloController.receive_call', Save the file and run it. $ sails lift You should see your basic server application in action at http://localhost:1337/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receive_call/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Sails application to forward calls Edit api/controllers/HelloController.js and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 var plivo = require('plivo'); module.exports = { forward_call: function(req, res) { var response = plivo.Response(); var dial = response.addDial(); dial.addNumber(''); res.setHeader("Content-type", "text/xml"); return res.status(200).send(response.toXML()); }, }; Replace the destination number placeholder with an actual phone number (for example, 12025551234). Edit config/route.js to set the route. 'POST /forward_call' : 'HelloController.forward_call', Save the file and run it. $ sails lift You should see your basic server application in action at http://localhost:1337/forward\_call/. If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-node-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Node.js using NestJS Framework | Plivo Voice * [Node.js & Express](/docs/voice/quickstart/node-expressjs/) * [Node.js & NestJS](/docs/voice/quickstart/node-nestjs/) * [Node.js & Sails](/docs/voice/quickstart/node-sails/) * [Node.js & serverless](/docs/voice/quickstart/node-serverless/) Get Started with Node.js using NestJS Framework =============================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up Your Node.js and NestJS dev environment ---------------------------------------------- You must set up and install Node.js and Plivo’s Node.js SDK before you make your first call. You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Edit the app.controller.ts file and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common'; import { Response } from 'express'; import { AppService } from './app.service'; const plivo = require('plivo'); @Controller() export class AppController { constructor(private readonly appService: AppService) {} @Get('/trigger_phlo/') triggerPhlo() { const PhloClient = plivo.PhloClient; const authId = ''; const authToken = ''; const phloId = ''; const phloClient = new PhloClient(authId, authToken); phloClient .phlo(phloId) .run() .then(function (result) { console.log('Phlo run result', result); }) .catch(function (err) { console.error('Phlo run failed', err); }); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit the app.controller.ts file and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common'; import { Response } from 'express'; import { AppService } from './app.service'; const plivo = require('plivo'); @Controller() export class AppController { constructor(private readonly appService: AppService) {} @Get('/trigger_phlo') triggerPhlo() { const PhloClient = plivo.PhloClient; const authId = ''; const authToken = ''; const phloId = ''; const payload = { from: '', to: '', }; const phloClient = new PhloClient(authId, authToken); phloClient .phlo(phloId) .run(payload) .then(function (result) { console.log('Phlo run result', result); }) .catch(function (err) { console.error('Phlo run failed', err); }); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and start the NestJS application. $ npm run start Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both PHLO and API/XML on our documentation pages. Install Node.js, NestJS, and the Plivo Node.js SDK -------------------------------------------------- You must set up and install Node.js, NestJS, and Plivo’s Node.js SDK before you make your first call. ### Install Node.js You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . ### Install NestJS Install Nest CLI using [npm](https://www.npmjs.com/package/@nestjs/cli) . $ npm i @nestjs/cli Choose the npm package manager when prompted for which package manager to use. Create a new NestJS project and change to the project directory. $ nest new plivovoice $ cd plivovoice ### Install the Plivo Node.js SDK Install the Plivo Node.js SDK using [npm](https://www.npmjs.com/package/plivo) . $ npm install plivo Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Edit `app.controller.ts` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common'; import { Response } from 'express'; import { AppService } from './app.service'; const plivo = require('plivo'); @Controller() export class AppController { constructor(private readonly appService: AppService) {} @Get('/outbound') makeCall() { const client = new plivo.Client( 'auth_id', 'auth_token', ); client.calls .create( '', '', 'https://s3.amazonaws.com/static.plivo.com/answer.xml', { answerMethod: 'GET', }, ) .then( function (response) { console.log(response); }, function (err) { console.error(err); }, ); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and retrieve them when initializing the client. ### Test Save the file and start the NestJS application. $ npm run start Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a NestJS server to handle incoming calls Edit `app.controller.ts` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common'; import { Response } from 'express'; import { AppService } from './app.service'; const plivo = require('plivo'); @Controller() export class AppController { constructor(private readonly appService: AppService) {} @Get('/outbound') makeCall() { ..........; ..........; } @Get('/inbound') xmlResponse(@Res() res: Response) { const response = plivo.Response(); const speak_body = 'Hello, you just received your first call'; response.addSpeak(speak_body); res.set('Content-Type', 'text/xml'); res.send(response.toXML()); } } Save the file and start the NestJS application. $ npm run start You should see your basic server application for inbound calls in action at http://localhost:3000/inbound/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a NestJS application to forward calls Create a file called `forward_call.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common'; import { Response } from 'express'; import { AppService } from './app.service'; const plivo = require('plivo'); @Controller() export class AppController { constructor(private readonly appService: AppService) {} @Get('/outbound') makeCall() { ..........; ..........; } @Get('/inbound') xmlResponse(@Res() res: Response) { ..........; ..........; } @Get('/forward') forwardCall(@Res() res: Response) { const response = plivo.Response(); const dial = response.addDial(); dial.addNumber(''); res.set('Content-Type', 'text/xml'); res.send(response.toXML()); } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-node-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the NestJS application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Pagination | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Pagination** -------------- Plivo uses offset-based pagination to list resources. For instance, if a search request has a result of 100 objects with limit = 10 and offset = 5, then objects with indices 51 through 60 are returned. ### **Parameters used for pagination** | | | | --- | --- | | **limit integer** | A limit on the number phone numbers to be returned. limit can range between 1 and 20, and the default is 20. | | **offset integer** | A pagination cursor to denote the number of objects by which the results should be offset. | Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Session | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) Session ======= Plivo’s Session API is a simple REST interface for sending and validating one-time passwords (OTP) for two-factor authentication (2FA) using SMS and voice channels. #### **API Endpoint** `POST` `https://api.plivo.com/v1/Account/{auth_id}/Verify/` Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # The Session Object | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **The Session object** ---------------------- The API creates a Session object once for each recipient within the code expiry time. You can configure your expiry time while creating applications. A Session object has these attributes. ### **Attributes** | | | | --- | --- | | **session\_uuid string** | A 36-character string that uniquely identifies a session detail record. | | **app\_uuid string** | ID of the application used to trigger the session. | | **recipient string** | The destination phone number (in E.164 format) to which the message was sent. | | **status string** | The current status of the session.

Allowed values: in-progress, verified and expired. | | **channel string** | The last channel used for the session. | | **locale string** | This is the language translation in which your session was attempted.

This feature is available upon request only. Raise a [support ticket](https://support.plivo.com/hc/en-us)
and provide the translations you want to use. | | **otp\_attempts object** | An object containing details of all the attempts made during a session and the same channel, ID, time, and status. | | **chargesobject** | An object containing details of all the charges incurred during a session and the same channel, ID, and charge. | | **created\_atstring** | UTC time when the session was created. | | **updated\_atstring** | UTC time when the session was last updated. | Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Node.js Using Serverless Framework | Plivo * [Node.js & Express](/docs/voice/quickstart/node-expressjs/) * [Node.js & NestJS](/docs/voice/quickstart/node-nestjs/) * [Node.js & Sails](/docs/voice/quickstart/node-sails/) * [Node.js & serverless](/docs/voice/quickstart/node-serverless/) Get Started with Node.js Using the Serverless Framework ======================================================= **Sign up for a Plivo account** ------------------------------- When you [sign up with Plivo](https://console.plivo.com/accounts/register/) , we give you a free trial account and free credits to experiment with and learn about our services. You can [add a number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS service features. Follow these steps to get a free trial account: 1. [Sign up](https://console.plivo.com/accounts/register/) with your work email address. 2. Check your inbox for an activation email message from Plivo. Click on the link in the message to activate your account. 3. Enter your mobile number to complete the phone verification step. ### **Sign up with your work email address** ![](/uploads/image10.jpg) If you have any issues creating a Plivo account, please contact our [support team](https://support.plivo.com/hc/en-us/) for assistance. To get started, try making a call either by using our API and XML documents, or via [PHLO](https://www.plivo.com/docs/phlo/) , our visual design tool, which allows you to create message flows using an intuitive canvas and deploy them with a few clicks. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Install Node.js, Serverless, Express, and the Plivo Node.js SDK --------------------------------------------------------------- You must set up and install Node.js, Serverless, Express, and Plivo Node.js SDK before you make your first outbound call. You also need an AWS account. If you don’t have an account, you can [create one](https://aws.amazon.com/) for free. ### **Install Node.js** You can check whether you have Node.js installed under macOS or Linux by running the command node --version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . ### Install Serverless, Express, and the Plivo Node.js SDK Create a project directory and change into it, then use [npm](https://www.npmjs.com/package/plivo) to create a new Node.js project. $ mkdir my-express-application && cd my-express-application $ npm init -f Install Serverless, Express, and the Plivo Node.js SDK using npm. $ npm install --save serverless-http express plivo You must have your AWS access key credentials loaded in the AWS\_ACCESS\_KEY\_ID and AWS\_SECRET\_ACCESS\_KEY environment variables. The Serverless framework accesses the values of these variables to publish the project to AWS. If you’ve never obtained these credentials from AWS before, the Serverless framework [documentation](https://www.serverless.com/framework/docs/providers/aws/guide/credentials) includes step-by-step instructions on how to do so. Once you’ve set up your development environment, you can start sending and receiving messages using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called **index.js** and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 const serverless = require('serverless-http'); const express = require('express') const bodyParser = require('body-parser') const plivo = require('plivo') const app = express() app.get('/trigger_phlo/', function(request, response) { var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run().then(function(result) { console.log('Phlo run result', result); }).catch(function(err) { console.error('Phlo run failed', err); }) }) module.exports.handler = serverless(app); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called **index.js** and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 const serverless = require('serverless-http'); const express = require('express') const bodyParser = require('body-parser') const plivo = require('plivo') const app = express() app.get('/trigger_phlo/', function(req, res) { var plivo = require('plivo'); var PhloClient = plivo.PhloClient; var authId = ''; var authToken = ''; var phloId = ''; var phloClient = phlo = null; var payload = { From: '', To: '' } phloClient = new PhloClient(authId, authToken); phloClient.phlo(phloId).run(payload).then(function (result) { console.log('Phlo run result', result); }).catch(function (err) { console.error('Phlo run failed', err); }); }) module.exports.handler = serverless(app); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). #### Test Save the file and run this command to deploy the application. $ sls deploy ![Deploy](https://docs.plivo.com/assets/posts/images/quickstart/serverless-deploy.png) AWS will report an endpoint on which you can find your application — for example, here it shows https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws. You should see your basic server application in action in the below URL. https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws/trigger\_phlo/. **Note:** If you’re using a Plivo Trial account, you can make calls only to phone numbers that have been verified with Plivo. You can verify (sandbox) a number by going to the console’s Phone Numbers > [Sandbox Numbers](https://console.plivo.com/phone-numbers/sandbox-numbers/) page. Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/node/) with code for both PHLO and API/XML on our documentation pages. Install Node.js, Serverless, Express, and the Plivo Node.js SDK --------------------------------------------------------------- You must set up and install Node.js, Serverless, Express, and Plivo Node SDK before you make your first outbound call. You also need an AWS account. If you don’t have an account, you can [create one](https://aws.amazon.com/) for free. ### Install Node.js You can check whether you have Node.js installed under macOS or Linux by running the command node –version in a terminal window. Under Windows, open a Windows command prompt or PowerShell and type node -v. If you don’t have Node.js installed or want a more current version, [download and install it](https://nodejs.org/en/download/) . **Install Serverless, Express, and the Plivo Node.js SDK** Create a project directory and change into it, then use [npm](https://www.npmjs.com/package/plivo) to create a new Node.js project. $ mkdir my-express-application && cd my-express-application $ npm init -f **Install Serverless, Express, and the Plivo Node.js SDK using npm.** $ npm install --save serverless-http express plivo You must have your AWS access key credentials loaded in the AWS\_ACCESS\_KEY\_ID and AWS\_SECRET\_ACCESS\_KEY environment variables. The Serverless framework accesses the values of these variables to publish the project to AWS. If you’ve never obtained these credentials from AWS before, the Serverless framework [documentation](https://www.serverless.com/framework/docs/providers/aws/guide/credentials) includes step-by-step instructions on how to do so. Once you’ve set up your development environment, you can start sending and receiving messages using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call -----------------------------   ![first outbound call](https://docs.plivo.com/assets/posts/images/quickstart/node-serverless-voice/image14.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use [https://s3.amazonaws.com/static.plivo.com/answer.xml](https://s3.amazonaws.com/static.plivo.com/answer.xml) as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](https://www.plivo.com/docs/voice/xml/overview/) documentation. ### Create a Serverless server Create a file called `index.js` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 const serverless = require('serverless-http'); const express = require('express') const plivo = require('plivo') const app = express() app.get('/outbound_call/', function(request, response) { let client = new plivo.Client('', ''); client.calls.create( "", "", "https://s3.amazonaws.com/static.plivo.com/answer.xml", { answerMethod: "GET", }, ).then(function(response) { console.log(response) }); }); module.exports.handler = serverless(app); Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your Plivo credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use process.env to store environment variables and fetch them when initializing the client. ### Create a Serverless configuration file In the project directory, create a configuration file called serverless.yml, which Serverless uses to handle deployments, and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 # serverless.yml service: my-express-application provider: name: aws runtime: nodejs16.x stage: dev region: us-east-1 functions: app: handler: index.handler url: true Run this command to deploy the application. $ sls deploy ![Deploy serverless](https://docs.plivo.com/assets/posts/images/quickstart/serverless-deploy.png) ### Test AWS will report an endpoint on which you can find your application — for example, here it shows https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws. You should see your basic server application in action at the below URL: https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws./outbound\_call/ **Note:** If you’re using a Plivo Trial account, you can send messages only to phone numbers that have been verified with Plivo. You can verify (sandbox) a number by going to the console’s Phone Numbers > [Sandbox Numbers](https://console.plivo.com/phone-numbers/sandbox-numbers/) page. Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](https://www.plivo.com/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . ### Modify the Serverless server Add the code to receive a call to the index.js file we already built. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 const serverless = require('serverless-http'); const express = require('express') const bodyParser = require('body-parser') const plivo = require('plivo') const app = express() app.use(bodyParser.urlencoded({ extended: true })); app.use(function(req, response, next) { response.contentType('application/xml'); next(); }); // make an outbound Call app.get('/outbound_call/', function(request, response) { ......// Make a call code }); // receive call app.get('/receive_call/', function(request, response) { var resp = plivo.Response(); var speak_body = "Hello, you just received your first call"; resp.addSpeak(speak_body); response.writeHead(200, {'Content-Type': 'text/xml'}); response.end(resp.toXML()); }); Run this command to deploy the application. $ sls deploy ![Deploy serverless](https://docs.plivo.com/assets/posts/images/quickstart/serverless-deploy.png) AWS will report an endpoint on which you can find your application — for example, here it shows https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws. You should see your basic server application in action at the below URL: https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws/receive\_call/ ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click Add New Application. You can also use Plivo’s [Application API](https://www.plivo.com/docs/account/api/application/#create-an-application) . Give your application a name — we called ours Receive\_call. Enter the server URL you want to use (for example https://.com/receive\_call/) in the Primary Answer URL field and set the method to POST. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select XML Application. From the Plivo Application drop-down, select Receive Call (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](https://www.plivo.com/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](https://www.plivo.com/docs/numbers/) . ### Modify the Serverless server 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 const serverless = require('serverless-http'); const express = require('express') const bodyParser = require('body-parser') const plivo = require('plivo') const app = express() app.use(bodyParser.urlencoded({ extended: true })); app.use(function(req, response, next) { response.contentType('application/xml'); next(); }); // make an outbound call app.get('/outbound_call/', function(request, response) { ...//Make a call }); // receive call app.get('/receive_call/', function(request, response) { ...// Receive a call code }); // Forward incoming call app.get('/forward_call/', function(request, response) { var resp = plivo.Response(); var dial = resp.addDial(); dial.addNumber(""); response.writeHead(200, { 'Content-Type': 'text/xml' }); response.end(resp.toXML()); }); Replace the destination number placeholder with an actual phone number (for example, 12025551234). Run this command to deploy the application. $ sls deploy ![Deploy serverless](https://docs.plivo.com/assets/posts/images/quickstart/serverless-deploy.png) AWS will report an endpoint on which you can find your application — for example, here it shows https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws. You should see your basic server application in action at the below URL: https://mps46xe2isjinod7x5yu5w3kza0hlrld.lambda-url.us-east-1.on.aws/forward\_call/ ### Create a Plivo application to forward calls Associate the Express application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on Add New Application, or use Plivo’s [Application API](https://www.plivo.com/docs/account/api/application/#create-an-application) . Give your application a name — we called ours Forward Call. Enter the server URL you want to use (for example https://.com/forward\_call/) in the Answer URL field and set the method to POST. Click Create Application to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select XML Application. From the Plivo Application drop-down, select Forward Call (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than a dozen use cases](https://www.plivo.com/docs/messaging/use-cases/send-an-sms/node/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # API Response | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) API Response ============ All Plivo API endpoints return a response in JSON format. An api\_id in each response uniquely identifies each request. The API returns one of these HTTP status codes depending on whether the API call is successful or not. ### **HTTP status codes we send** | | | | --- | --- | | **200** | Request has been executed | | **201** | Resource created | | **202** | Resource changed | | **204** | Resource deleted | | **400** | A parameter is missing or is invalid | | **401** | Authentication failed | | **404** | Resource cannot be found | | **405** | HTTP method is not allowed | | **429** | You are sending too many requests | | **500** | Server error | Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Java Using Spring Framework| Plivo Voice * [Java & Spring](/docs/voice/quickstart/java-spring/) * [Java & Spark](/docs/voice/quickstart/java-spark/) Get Started with Java Using Spring Framework ============================================ Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set Up Your Java Spring Dev Environment --------------------------------------- You must set up and install Java 1.8 or higher and Plivo’s Java SDK before you make your first call. You can check your Java version under macOS or Linux by running the command java -version in a terminal window. Under Windows there are [several ways to check](https://www.java.com/en/download/help/version_manual.html) . If you don’t have Java installed or need a more current version, [download and install it](https://www.oracle.com/java/technologies/downloads/) . You should also [download and install IntelliJ Idea](https://www.jetbrains.com/idea/download/) . ### Install Spring and the Plivo Java package using IntelliJ Idea Use [Spring Initializr](https://start.spring.io/) to create a boilerplate project with the Spring Boot framework. ![Create Boilerplate code](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/initializr.png) Choose the Spring Web dependency. Give the project a friendly name and click **Generate** to download the boilerplate code and open it in IntelliJ Idea. ![Boilerplate project in IntelliJ](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/boilerplate.png) **Note:** Set the Java target as 8. Install the Plivo Java package by adding the dependency in `pom.xml` com.plivo plivo-java 5.9.3 ![Install Plivo package](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/plivo-java.png) Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Edit the PlivoVoiceApplication.java file in the src/main/java/com.example.demo/ folder and paste into it this code. **Note:** Here, the demo application name is PlivoVoiceApplication.java because the friendly name we provided in [Spring Initializr](https://start.spring.io/) was Plivo Voice. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 package com.example.demo; import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import com.plivo.api.models.phlo.PhloUpdateResponse; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import java.io.IOException; @SpringBootApplication @RestController public class PlivoVoiceApplication { public static void main(String[] args) { SpringApplication.run(PlivoVoiceApplication.class, args); } @GetMapping("/outbound") public PhloUpdateResponse triggerPhlo() throws IOException, PlivoRestException { final String authId = ""; final String authToken = ""; PlivoClient client = new PlivoClient(authId, authToken); String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); PhloUpdateResponse response = Phlo.updater(phloId).run(); return response; } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Edit the PlivoVoiceApplication.java file in the src/main/java/com.example.demo/ folder and paste into it this code. **Note:** Here, the demo application name is PlivoVoiceApplication.java because the friendly name provided in [Spring Initializr](https://start.spring.io/) was Plivo Voice. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 package com.example.demo; import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import com.plivo.api.models.phlo.PhloUpdateResponse; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import java.io.IOException; import java.util.HashMap; import java.util.Map; @SpringBootApplication @RestController public class PlivoVoiceApplication { public static void main(String[] args) { SpringApplication.run(PlivoVoiceApplication.class, args); } @GetMapping("/outbound") public PhloUpdateResponse triggerPhlo() throws IOException, PlivoRestException { final String authId = ""; final String authToken = ""; PlivoClient client = new PlivoClient(authId, authToken); String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); Map payload = new HashMap<>(); payload.put("from", ""); payload.put("to", ""); PhloUpdateResponse response = Phlo.updater(phloId).payload(payload).run(); return response; } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it from IntelliJ Idea. Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you have created and configured your PHLO, assign your PHLO to a Plivo number. #### To assign a PHLO to a number: Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an Incoming call ------------------------ You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/java/) with code for both PHLO and API/XML on our documentation pages. Install Java, Spring, and the Plivo Java SDK -------------------------------------------- You must set up and install Java 1.8 or higher, Spring, and Plivo’s Java SDK before you make your first call. ### Install Java You can check your Java version under macOS or Linux by running the command java -version in a terminal window. Under Windows there are [several ways to check](https://www.java.com/en/download/help/version_manual.html) . If you don’t have Java installed or need a more current version, [download and install it](https://www.oracle.com/java/technologies/downloads/) . You should also [download and install IntelliJ Idea](https://www.jetbrains.com/idea/download/) . ### Create a Spring application Use [Spring Initializr](https://start.spring.io/) to create a boilerplate project with the Spring Boot framework. ![Create Boilerplate code](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/initializr.png) Choose the Spring Web dependency. Give the project a friendly name — we used Plivo Voice — and click **Generate** to download boilerplate code, which will be named PlivoVoiceApplication.java based on the friendly name we supplied. Open it in IntelliJ Idea. ![Boilerplate project in IntelliJ](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/boilerplate.png) ### Install the Plivo Java SDK using IntelliJ Idea Install the Plivo Java SDK by adding the dependency in `pom.xml`. com.plivo plivo-java 5.9.3 ![Install Plivo package](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/plivo-java.png) Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Edit the `PlivoVoiceApplication.java` file in src/main/java/com.example.demo/ and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 package com.example.demo; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.call.Call; import com.plivo.api.models.call.CallCreateResponse; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import com.plivo.api.exceptions.PlivoXmlException; import java.io.IOException; import java.util.Collections; @SpringBootApplication @RestController public class PlivoVoiceApplication { public static void main(String[] args) { SpringApplication.run(PlivoVoiceApplication.class, args); } @GetMapping(value="/outbound", produces={"application/json"}) public CallCreateResponse makeCall() throws PlivoXmlException, IOException, PlivoRestException { Plivo.init("",""); CallCreateResponse response = Call.creator("", Collections.singletonList(""), "https://s3.amazonaws.com/static.plivo.com/answer.xml") .answerMethod("GET") .create(); System.out.println(response); return response; } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use System.getenv() to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. ![Make Call](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/run.png) Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Spring application to handle incoming calls Edit the `PlivoVoiceApplication.java` file in src/main/java/com.example.demo/ and paste this code into it after the makeCall function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 package com.example.demo; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.call.Call; import com.plivo.api.models.call.CallCreateResponse; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import com.plivo.api.exceptions.PlivoXmlException; import com.plivo.api.xml.Response; import com.plivo.api.xml.Speak; import java.io.IOException; import java.util.Collections; @SpringBootApplication @RestController public class PlivoVoiceApplication { public static void main(String[] args) { SpringApplication.run(PlivoVoiceApplication.class, args); } @GetMapping(value="/outbound", produces={"application/json"}) public CallCreateResponse makeCall() throws PlivoXmlException, IOException, PlivoRestException { ........; ........; } @GetMapping(value="/inbound", produces={"application/xml"}) public String receiveCall() throws PlivoXmlException { return new Response() .children(new Speak("Hello, you just received your first call")).toXmlString(); } } **Note:** Please update the import declaration section as well. ![Receive Call](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/inbound.png) Run the project and you should see your basic server application in action at http://localhost:8080/inbound/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Spring application to forward calls Edit the `PlivoVoiceApplication.java` file in src/main/java/com.example.demo/ and paste this code into it after the receiveCall function block. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 package com.example.demo; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.call.Call; import com.plivo.api.models.call.CallCreateResponse; import com.plivo.api.xml.Dial; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import com.plivo.api.exceptions.PlivoXmlException; import com.plivo.api.xml.Response; import com.plivo.api.xml.Speak; import com.plivo.api.xml.Number; import java.io.IOException; import java.util.Collections; @SpringBootApplication @RestController public class PlivoVoiceApplication { public static void main(String[] args) { SpringApplication.run(PlivoVoiceApplication.class, args); } @GetMapping(value="/outbound", produces={"application/json"}) public CallCreateResponse makeCall() throws PlivoXmlException, IOException, PlivoRestException { ........; ........; } @GetMapping(value="/inbound", produces={"application/xml"}) public String receiveCall() throws PlivoXmlException { ........; ........; } @GetMapping(value="/forward", produces={"application/xml"}) public String forwardCall(@RequestParam("From") String fromNumber) throws PlivoXmlException { Response res = new Response() .children( new Dial() .callerId(fromNumber) .children( new Number("") ) ); // Returns the XML return res.toXmlString(); } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-java-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Java application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/java/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Go Using Gin Web Framework | Plivo Voice * [Go & Gin](/docs/voice/quickstart/go-gin/) * [Go & Martini](/docs/voice/quickstart/go-martini/) Get Started with Go Using Gin Web Framework =========================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Go Gin dev environment ---------------------------------- You must set up and install Go and Plivo’s Go SDK before you make your first call. ### Install Go [Download and install Go](https://go.dev/dl/) from its official site. ### Install the Plivo Go and Gin packages Create a projects directory and change into it. $ mkdir mygoapp $ cd mygoapp Install the Plivo and Gin Go packages using the `go` command. $ go get github.com/plivo/plivo-go/v7 $ go get github.com/gin-gonic/gin You can also install them by cloning the [Plivo Go repository](https://github.com/plivo/plivo-go) and [Gin repository](https://github.com/gin-gonic/gin) into your `GOPATH`. Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `TriggerPhlo.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 package main import ( "fmt" "github.com/gin-gonic/gin" "github.com/plivo/plivo-go/v7" ) // Initialize the following params with corresponding values to trigger resources const authId = "" const authToken = "" const phloId = "" func main() { r := gin.Default() r.GET("/trigger-phlo", func(c *gin.Context) { c.Header("Content-Type", "application/JSON") phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } response, err := phloGet.Run(nil) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) c.JSON(200, response) }) r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 package main import ( "fmt" "github.com/gin-gonic/gin" "github.com/plivo/plivo-go/v7" ) // Initialize the following params with corresponding values to trigger resources const authId = "" const authToken = "" const phloId = "" func main() { r := gin.Default() r.GET("/trigger-phlo", func(c *gin.Context) { c.Header("Content-Type", "application/JSON") phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } //pass corresponding from and to values type params map[string]interface{} response, err := phloGet.Run(params{ "from": "", "to": "", }) if err != nil { println(err) } fmt.Printf("Response: %#v\n", response) c.JSON(200, response) }) r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ go run TriggerPhlo.go Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an inbound call ----------------------- You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/go/) with code for both PHLO and API/XML on our documentation pages. Install Go, Gin, and the Plivo Go SDK ------------------------------------- You must set up and install Go, Gin, and Plivo’s Go SDK before you make your first call. ### Install Go [Download and install Go](https://go.dev/dl/) from its official site. ### Install Gin and the Plivo Go SDK Create a projects directory and change into it. $ mkdir mygoapp $ cd mygoapp Install the Plivo and Gin Go packages using the `go` command. $ go get github.com/plivo/plivo-go/v7 $ go get github.com/gin-gonic/gin You can also install them by cloning the [Plivo Go repository](https://github.com/plivo/plivo-go) and [Gin repository](https://github.com/gin-gonic/gin) into your `GOPATH`. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Create a file called `MakeCall.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 package main import ( "fmt" "github.com/gin-gonic/gin" "github.com/plivo/plivo-go/v7" ) func main() { r := gin.Default() r.GET("/outbound-call", func(c *gin.Context) { c.Header("Content-Type", "application/JSON") client, err := plivo.NewClient("", "", &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } response, err := client.Calls.Create( plivo.CallCreateParams{ From: "", To: "", AnswerURL: "https://s3.amazonaws.com/static.plivo.com/answer.xml", AnswerMethod: "GET", }, ) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) c.JSON(200, response) }) r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.Setenv and os.Getenv functions to store environment variables and fetch them when initializing the client. ### Test Save the file and run it. $ go run MakeCall.go Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. To be able to host answer and callback URLs and to be able to provide valid XML and accept notifications on these URLs, you need to host a web server. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Go Gin server to handle incoming calls Create a file called `receive_call.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 package main import ( "github.com/gin-gonic/gin" "github.com/plivo/plivo-go/v7/xml" ) func main() { r := gin.Default() r.GET("/receive_call", func(c *gin.Context) { c.Header("Content-Type", "application/xml") response := xml.ResponseElement{ Contents: []interface{}{ new(xml.SpeakElement). AddSpeak("Hello, you just received your first call", "MAN", "en-US", 1), }, } c.String(200, response.String()) }) r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") } Save the file and run it. $ go run receive_call.go You should see your basic server application in action at http://localhost:8080/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (8080 in this case): ./ngrok http 8080 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-go-gin.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Go Gin server to forward calls Create a file called `forward_call.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 package main import ( "github.com/gin-gonic/gin" "github.com/plivo/plivo-go/v7/xml" ) func main() { r := gin.Default() r.GET("/forward_call", func(c *gin.Context) { c.Header("Content-Type", "application/xml") response := xml.ResponseElement{ Contents: []interface{}{ new(xml.DialElement). SetContents( []interface{}{ new(xml.NumberElement). SetContents(""), }, ), }, } c.String(200, response.String()) }) r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080") } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-go-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Go application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/go/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Java Using Spark Framework| Plivo Voice * [Java & Spring](/docs/voice/quickstart/java-spring/) * [Java & Spark](/docs/voice/quickstart/java-spark/) Get Started with Java Using Spark Framework =========================================== Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Java Spark dev environment -------------------------------------- You must set up and install Java 1.8 or higher and Plivo’s Java SDK before you make your first call. You can check your Java version under macOS or Linux by running the command java -version in a terminal window. Under Windows there are [several ways to check](https://www.java.com/en/download/help/version_manual.html) . If you don’t have Java installed or need a more current version, [download and install it](https://www.oracle.com/java/technologies/downloads/) . You should also [download and install IntelliJ Idea](https://www.jetbrains.com/idea/download/) . ### Install the Plivo Java package using IntelliJ Idea Create a new project in IntelliJ Idea. ![Create New Project](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/step1.png) Choose a dependency management tool and Java SE SDK for the new project. ![Choose Dependency management](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/step2.png) Install the Plivo Java package by adding the dependency in `pom.xml`. * Install the Plivo Java, Spark & SLF4j package by adding the dependency in `pom.xml` com.sparkjava spark-core 2.9.1 org.slf4j slf4j-simple 1.7.21 com.plivo plivo-java 5.9.3 ![Install package](https://docs.plivo.com/assets/posts/images/sms/quickstart/java/spark.png) Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a Java class in the project called `TriggerPhlo` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 package com.plivo.api.samples.call; import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import com.plivo.api.models.phlo.PhloUpdateResponse; import java.io.IOException; import static spark.Spark.*; class Example { public static void main(String[] args) { get("/trigger_phlo", (req, resp) -> { try { final String authId = ""; final String authToken = ""; PlivoClient client = new PlivoClient(authId, authToken); { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); PhloUpdateResponse response = Phlo.updater(phloId).run(); return response; } } catch (PlivoRestException | IOException exception) { return exception; } }); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a Java class in the project called `TriggerPhlo` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 package com.plivo.api.samples.call; import com.plivo.api.Plivo; import com.plivo.api.PlivoClient; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.phlo.Phlo; import com.plivo.api.models.phlo.PhloUpdateResponse; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static spark.Spark.*; class Example { public static void main(String[] args) { get("/trigger_phlo_with_payload", (req, resp) -> { try { final String authId = ""; final String authToken = ""; PlivoClient client = new PlivoClient(authId, authToken); { String phloId = ""; Plivo.init(authId, authToken); Phlo phlo = Phlo.getter(phloId).client(client).get(); Map payload = new HashMap<>(); payload.put("from", ""); payload.put("to", ""); PhloUpdateResponse response = Phlo.updater(phloId).payload(payload).run(); return response; } } catch (PlivoRestException | IOException exception) { return exception; } }); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it from IntelliJ Idea. Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you have created and configured your PHLO, assign your PHLO to a Plivo number. #### To assign a PHLO to a number: Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an Incoming call ------------------------ You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/java/) with code for both PHLO and API/XML on our documentation pages. Install Java, Spark, and the Plivo Java SDK ------------------------------------------- You must set up and install Java 1.8 or higher, Spark, and Plivo’s Java SDK before you make your first call. ### Install Java You can check your Java version under macOS or Linux by running the command java -version in a terminal window. Under Windows there are [several ways to check](https://www.java.com/en/download/help/version_manual.html) . If you don’t have Java installed or need a more current version, [download and install it](https://www.oracle.com/java/technologies/downloads/) . You should also [download and install IntelliJ Idea](https://www.jetbrains.com/idea/download/) . ### Install Spark and the Plivo Java SDK using IntelliJ Idea Create a new project in IntelliJ Idea. ![Create New Project](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/step1.png) Choose a dependency management tool and Java SE SDK for the new project. ![Choose Dependency management](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/step2.png) Install the Plivo Java SDK, Spark, and SLF4J by adding dependencies in `pom.xml`. com.plivo plivo-java 5.8.0 com.sparkjava spark-core 2.9.1 org.slf4j slf4j-simple 1.7.21 Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Create a Java class in the project called `MakeCall` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 package com.plivo.api.samples.call; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.call.Call; import com.plivo.api.models.call.CallCreateResponse; import java.io.IOException; import java.util.Collections; import static spark.Spark.*; public class MakeCall { public static void main(String[] args) { get("/outbound_call", (req, resp) -> { Plivo.init("", ""); try { CallCreateResponse response = Call.creator("", Collections.singletonList(""), "https://s3.amazonaws.com/static.plivo.com/answer.xml") .answerMethod("GET") .create(); return response; } catch (PlivoRestException | IOException exception) { return exception; } }); } } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use System.getenv() to store environment variables and retrieve them when initializing the client. ### Test Save the file and run it. ![Make Call](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/makecall.png) Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Spark webapp to handle incoming calls Create a Java class named `ReceiveCall` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 import static spark.Spark.*; import com.plivo.api.xml.Speak; import com.plivo.api.xml.Response; public class ReceiveCall { public static void main(String[] args) { post("/receive_call/", (request, response) -> { response.type("application/xml"); return new Response() .children(new Speak("Hello, you just received your first call")).toXmlString(); }); } } ![Receive Call](https://docs.plivo.com/assets/posts/images/voice/quickstart/java/receivecall.png) Run the project and you should see your basic server application in action at http://localhost:4567/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (80 in this case): ./ngrok http 80 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Spark webapp to forward calls Create a Java class called `ForwardCall` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 import static spark.Spark.*; import com.plivo.api.xml.Dial; import com.plivo.api.xml.Number; import com.plivo.api.xml.Response; public class forwardcall { public static void main(String[] args) { get("/forward_call/", (request, response) -> { String from_number = request.queryParams("From"); response.type("application/xml"); Response res = new Response() .children( new Dial() .callerId(from_number) .children( new Number("") ) ); // Returns the XML return res.toXmlString(); }); } } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-java-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Java application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/java/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started with Go | Plivo Voice * [Go & Gin-Gonic](/docs/voice/quickstart/go-gin/) * [Go & Martini](/docs/voice/quickstart/go-martini/) Get Started with Go Using Martini ================================= Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below. * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_phlo_active.svg)Using PHLO](#phlo) * [![](https://docs.plivo.com/assets/dist/images/v2/icon/ic_xml.svg)Using XML](#xml) * * * Set up your Go Martini dev environment -------------------------------------- You must set up and install Go and Plivo’s Go SDK before you make your first call. ### Install Go [Download and install Go](https://go.dev/dl/) from its official site. ### Install the Plivo Go and Martini packages Create a projects directory and change into it. $ mkdir mygoapp $ cd mygoapp Install the Plivo and Martini Go packages using the `go` command. $ go get github.com/plivo/plivo-go/v7 $ go get github.com/go-martini/martini You can also install them by cloning the [Plivo Go repository](https://github.com/plivo/plivo-go) and [Martini repository](https://github.com/go-martini/martini) into your `GOPATH`. Once you’ve set up your development environment, you can start making and receiving calls using [PHLO](/docs/phlo/) , our visual workflow design studio, or using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- You can create and deploy a PHLO to make an outbound call with a few clicks on the PHLO canvas, and trigger it with some simple code. ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Initiate Call** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **API Request** trigger state to the **Initiate Call** node. * In the Configuration pane at the right of the canvas, configure the **Initiate Call** node with a caller ID in the **From** field. Enter the destination number you wish to call in the **To** field. **Note:** You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through [Liquid](https://shopify.github.io/liquid/) templating parameters when you trigger the PHLO from your application. * Once you’ve configured the node, click **Validate** to save the configuration. * Similarly, create a node from the **Play Audio** component. Connect the **Initiate Call** node to the **Play Audio** node using the **Answered** trigger state. * Configure the **Play Audio** node to play a message to the user by entering text in the Speak Text box in the Prompt section of the Configuration pane — for example, “Hello, you just received your first call.” * Connect the **Initiate Call** node’s **Answered** trigger state to the **Play Audio** node. * After you complete the configuration, give the PHLO a name by clicking in the upper left, then click **Save**. Your PHLO is now ready to test. ### Trigger the PHLO You integrate a PHLO into your application workflow by making an API request to trigger the PHLO with the required payload — the set of parameters you pass to the PHLO. You can define a static payload by specifying values when you create the PHLO, or define a dynamic payload by passing values through parameters when you trigger the PHLO from your application. In either case, you need your Auth ID and Auth Token, which you can get from the overview page of the Plivo [console](https://console.plivo.com/dashboard/) . ![AUTHID](https://docs.plivo.com/assets/posts/images/Tropo-migration/AuthID.png) You also need the PHLO ID, which you can copy from the [PHLO list](https://console.plivo.com/phlo/list/) page. ![PHLO List](https://docs.plivo.com/assets/posts/images/phlo/Phlo_listing.jpg) #### With a static payload When you configure values when creating the PHLO, they act as a static payload. ![With Static Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/static_payload.png) #### Code Create a file called `TriggerPhlo.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 package main import ( "fmt" "plivo-go" ) // Initialize the following params with corresponding values to trigger resources const authId = "" const authToken = "" const phloId = "" func main() { testPhloRunWithoutParams() } func testPhloRunWithoutParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } response, err := phloGet.Run(nil) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . #### With a dynamic payload To use dynamic values for the parameters, use Liquid templating parameters when you create the PHLO and pass the values from your code when you trigger it. ![With Dynamic Payload](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/ob_call/dynamic_payload.png) #### Code Create a file called `TriggerPhlo.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 package main import ( "fmt" "plivo-go" ) // Initialize the following params with corresponding values to trigger resources const authId = "" const authToken = "" const phloId = "" func main() { testPhloRunWithParams() } func testPhloRunWithParams() { phloClient, err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } phloGet, err := phloClient.Phlos.Get(phloId) if err != nil { fmt.Print("Error", err.Error()) return } //pass corresponding from and to values type params map[string]interface{} response, err := phloGet.Run(params{ "from": "", "to": "", }) if err != nil { println(err) } fmt.Printf("Response: %#v\n", response) } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phlo\_id placeholder with your PHLO ID from the [Plivo console](https://console.plivo.com/phlo/list/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). ### Test Save the file and run it. $ go run TriggerPhlo.go Receive your first inbound call ------------------------------- You can create and deploy a PHLO to receive an inbound call with a few clicks on the PHLO canvas, without writing a single line of code. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Play Audio** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node’s **Incoming Call** trigger state to the **Play Audio** node. * In the Configuration pane at the right of the canvas, configure the **Play Audio** node to play a message to the caller. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign it to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-receive.png) ### Test You can now make a call to your Plivo phone number and see how the inbound call is handled. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . Forward an incoming call ------------------------ You can create and deploy a workflow to implement call forwarding with a few clicks on the PHLO canvas. ### Prerequisite To receive incoming calls, you must have a voice-enabled Plivo phone number. You can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Create the PHLO To create a PHLO, visit the [PHLO](https://console.plivo.com/phlo/list/) page of the Plivo console. If this is your first PHLO, the PHLO page will be empty. ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) * Click **Create New PHLO**. * In the **Choose your use case** pop-up, click **Build my own**. The PHLO canvas will appear with the **Start** node. **Note:** The Start node is the starting point of any PHLO. It lets you trigger a PHLO to start upon one of three actions: incoming SMS message, incoming call, or API request. * From the list of components on the left side, drag and drop the **Call Forward** component onto the canvas. When a component is placed on the canvas it becomes a node. * Draw a line to connect the **Start** node‘s **Incoming Call** trigger state to the **Call Forward** node. * In the Configuration tab at the right of the canvas, configure the **Call Forward** node to select the From number using a variable. Enter two curly brackets to view all available variables, and choose the appropriate one. Enter all the numbers you want to call in the To field, separated with commas. * Once you’ve configured the node, click **Validate** to save the configuration. * Give the PHLO a name by clicking in the upper left, then click **Save**. ### Assign the PHLO to a Plivo number Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number. * On the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the console, under **Your Numbers**, click the phone number you want to use for the PHLO. * In the **Number Configuration** box, select **PHLO** from the **Application Type** drop-down. * From the **PHLO Name** drop-down, select the PHLO you want to use with the phone number, then click **Update Number**. ![Assign PHLO to a Plivo Number](https://docs.plivo.com/assets/posts/images/voice/essential-guides/phlo/assign-phlo-forward.png) ### Test You can now call your Plivo phone number and see how the inbound call is forwarded. For more information about creating a PHLO application, see the [PHLO Getting Started guide](/docs/phlo/) . For information on components and their variables, see the [PHLO Components Library](/docs/phlo/components/) . More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/go/) with code for both PHLO and API/XML on our documentation pages. Install Go, Martini, and the Plivo Go SDK ----------------------------------------- You must set up and install Go, Martini, and Plivo’s Go SDK before you make your first call. ### Install Go [Download and install Go](https://go.dev/dl/) from its official site. ### Install Martini and the Plivo Go SDK Create a projects directory and change into it. $ mkdir mygoapp $ cd mygoapp Install the Plivo and Martini Go packages using the `go` command. $ go get github.com/plivo/plivo-go/v7 $ go get github.com/go-martini/martini You can also install them by cloning the [Plivo Go repository](https://github.com/plivo/plivo-go) and [Martini repository](https://github.com/go-martini/martini) into your `GOPATH`. Once you’ve set up your development environment, you can start making and receiving calls using our APIs and XML documents. Here are three common use cases to get you started. Make your first outbound call ----------------------------- ![Outbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/outbound-calls.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as an answer URL to test your first outgoing call. The file contains this XML code: Congratulations! You've made your first outbound call! This code instructs Plivo to say, “Congratulations! You’ve made your first outbound call!” to the call recipient. You can find the entire list of valid Plivo XML verbs in our [XML Reference](/docs/voice/xml/overview/) documentation. ### Code Create a file called `MakeCall.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 package main import "fmt" import "github.com/plivo/plivo-go/v7" func main() { client, err := plivo.NewClient("","", &plivo.ClientOptions{}) if err != nil { fmt.Print("Error", err.Error()) return } response, err := client.Calls.Create( plivo.CallCreateParams{ From: "", To: "", AnswerURL: "https://s3.amazonaws.com/static.plivo.com/answer.xml", AnswerMethod: "GET", }, ) if err != nil { fmt.Print("Error", err.Error()) return } fmt.Printf("Response: %#v\n", response) } Replace the auth placeholders with your authentication credentials from the [Plivo console](https://console.plivo.com/dashboard/) . Replace the phone number placeholders with actual phone numbers in [E.164 format](https://en.wikipedia.org/wiki/E.164) (for example, +12025551234). **Note:** We recommend that you store your credentials in the auth\_id and auth\_token environment variables to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and Plivo will automatically fetch the values from the environment variables. You can use os.Setenv and os.Getenv functions to store environment variables and fetch them when initializing the client. ### Test Save the file and run it. $ go run MakeCall.go Receive your first inbound call ------------------------------- ![Inbound Call Flow](https://docs.plivo.com/assets/posts/images/voice/essential-guides/xml/receive-incoming-calls.png) Plivo requests an answer URL when it answers the call (step 2) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo’s text-to-speech engine plays a message using the [Speak](/docs/voice/xml/speak/) XML element. To be able to host answer and callback URLs and to be able to provide valid XML and accept notifications on these URLs, you need to host a web server. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Go Martini server to handle incoming calls Create a file called `receive_call.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 package main import ( "github.com/go-martini/martini" "github.com/plivo/plivo-go/v7/xml" "net/http" ) func main() { m := martini.Classic() m.Get("/receive_call/", func(w http.ResponseWriter, r *http.Request) string { w.Header().Set("Content-Type", "application/xml") return xml.ResponseElement{Contents: []interface{}{ new(xml.SpeakElement). AddSpeak("Hello, you just received your first call"), }}.String() }) m.Run() } Save the file and run it. $ go run receive_call.go You should see your basic server application in action at http://localhost:8080/receive\_call/. ### Expose your local server to the internet To receive incoming calls, your local server must connect with Plivo API services. For that, we recommend using [ngrok](https://ngrok.com/download) , which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server. ![ngrok block diagram](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-diagram.png) Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive calls (8080 in this case): ./ngrok http 8080 This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. ![Sample ngrok CLI](https://docs.plivo.com/assets/posts/images/sms/quickstart/ngrok-go-gin.png) ### Create a Plivo application to receive calls Associate the controller you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) and click **Add New Application**. You can also use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Receive_call`. Enter the server URL you want to use (for example `https://.com/receivecall/`) in the `Primary Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ![Create Application](https://docs.plivo.com/assets/posts/images/voice/quickstart/receive_call_core.jpg) ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Receive Call` (the name we gave the application). Click **Update Number** to save. ![Assign Phone Number to Receive Call App](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_receive_call_core.jpg) ### Test Make a call to your Plivo number using any phone. Forward an incoming call ------------------------ ![Call Forward Call Flow](https://docs.plivo.com/assets/posts/images/voice/advanced-guides/xml/call-forward.png) Plivo requests an answer URL when the call is answered (step 4) and expects the file at that address to hold a valid XML response from the application with instructions on how to handle the call. In this example, when an incoming call is received, Plivo forwards the call using the [Dial XML](/docs/voice/xml/dial/) element. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the [Numbers](https://console.plivo.com/active-phone-numbers/) page of the Plivo console, or by using the [Numbers API](/docs/numbers/) . ### Set up a Go Martini server to forward calls Create a file called `forward_call.go` and paste into it this code. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 package main import ( "net/http" "plivo-go/xml" ) func handler(w http.ResponseWriter, r *http.Request) { response := xml.ResponseElement{ Contents: []interface{}{ new(xml.DialElement). SetContents( []interface{}{ new(xml.NumberElement). SetContents(""), }, ), }, } w.Write([]byte(response.String())) } func main() { http.HandleFunc("/forward_call/", handler) http.ListenAndServe(":8080", nil) } Replace the destination number placeholder with an actual phone number (for example, 12025551234). If you haven’t done so already, [expose your local server to the internet](/docs/sdk/server/set-up-go-dev-environment-api-messaging/#ngrok-setup) . ### Create a Plivo application to forward calls Associate the Go application you created with Plivo by creating a Plivo application. Visit Voice > [Applications](https://console.plivo.com/voice/applications/) in the Plivo console and click on **Add New Application**, or use Plivo’s [Application API](/docs/account/api/application/#create-an-application) . Give your application a name — we called ours `Forward Call`. Enter the server URL you want to use (for example `https://.com/forward_call/`) in the `Answer URL` field and set the method to `POST`. Click **Create Application** to save your application. ### Assign a Plivo number to your application Navigate to the [Numbers](https://console.plivo.com/number/) page and select the phone number you want to use for this application. From the Application Type drop-down, select `XML Application`. From the Plivo Application drop-down, select `Forward Call` (the name we gave the application). Click **Update Number** to save. ![Assign call forward application](https://docs.plivo.com/assets/posts/images/voice/quickstart/assign_forwardcall.jpg) ### Test Make a call to your Plivo number using any phone. Plivo will send a request to the answer URL you provided requesting an XML response and then forward the call according to the instructions in the XML document the server provides. More use cases -------------- We illustrate [more than 20 use cases](/docs/voice/use-cases/make-outbound-calls/go/) with code for both API/XML and PHLO on our documentation pages. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Create a session | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Create a session** -------------------- This API lets you send OTPs via Plivo’s SMS or Voice services. #### **API Endpoint** `POST` `https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/` ### **Arguments** | | | | --- | --- | | **app\_uuid stringoptional** | The UUID of the application you want to use for this session. Defaults to UUID of the default application for your account. | | **recipient stringrequired** | The phone number to which the message is to be delivered. | | **channel stringoptional** | The channel you want to use for sending the code.

Allowed values:sms,voice
Defaults tosms | | **method stringoptional** | The HTTP method to be used when calling the URL defined above.

Allowed values:GET,POST
Defaults toPOST | | **Url stringoptional** | Set this parameter to the fully qualified URL to which status update callbacks for the session should be sent. Read more about the session [attributes passed to this callback URL](https://regal-island.cloudvent.net/docs/messaging/api/message/)
. | | **locale stringoptional** | Set this parameter to determine the language you want to use. Defaults to ‘en’.

The locale value is obtained by combining language code in ISO 639-1 format and region code in ISO 3166-1 format (optional). For example: en\_US, en, en\_GB, es, fr\_FR etc.

This feature is available upon request only. Raise a [support ticket](https://support.plivo.com/hc/en-us)
and provide the translations you want to use. | | **brand\_namestringoptional** | This is the brand name that users will see in their Verify messages. It replaces the string “${brand\_name}“ in the Verify template of your choice. It is relevant to the ‘Voice’ and 'SMS' channels.

Please note that passing a brand\_name overrides the Brand Name configured in the Verify application. | | **app\_hashstringoptional** | Relevance: 'SMS' Channel and Android OS only

This is the text string that the [SMS Retriever API](https://developers.google.com/identity/sms-retriever/overview)
will look for to match the received SMS OTP to your android application. Please refer to [Google's documentation](https://developers.google.com/identity/sms-retriever/verify#computing_your_apps_hash_string)
on how to compute your app's hash string. The “app\_hash” will be appended at the end of your verification SMS body. | | **code\_lengthintegeroptional** | Valid Values: 4 to 8 (inclusive)
Set this parameter to override the default length of the code/OTP as defined in the configuration of the relevant Verify application. | ### **Returns** Returns a JSON response containing the API request ID and session UUID. ### Response { "api_id": "3335cb16-d297-4e00-a5e6-66d2bb03b323", "message": "Session initiated", "session_uuid": "8e712097-8090-4644-81e7-8f4265d8354e" } ### Example Request 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 import sys sys.path.append("../plivo-python") import plivo client = plivo.RestClient('','') response = client.verify_session.create( recipient='', app_uuid='', channel='', url='', method='' ) print(response) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 require "rubygems" require "/usr/src/app/lib/plivo.rb" include Plivo # Environment api = RestClient.new("", "") app_uuid='' channel='' url='https://.com/session_status/' method='POST' recipient='' begin puts("Create Session") response = client.verify_session.create(app_uuid,recipient,channel,url,method) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 let plivo = require('plivo') let client = new plivo.Client('',''); client.verify_session.create({ app_uuid:'', recipient: '', url:'https://.com/sms_status/', method:'POST', channel:'sms' }).then(function(response) { console.log(response) }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 ", ""); $optionalArgs=array("url" => "https://.com/sms_status/", "method" =>"POST", "channel"=>"sms","app_uuid"=>""); // Create Session try { $response1 = $client->verifySessions->create( "",$optionalArgs ); print_r($response1); } catch (Exception $ex) { print_r($ex); } ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 import java.io.IOException; import java.net.URL; import java.util.Collections; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.verify_session.VerifySession; import com.plivo.api.models.verify_session.SessionCreateResponse; import com.plivo.api.models.message.Message; import com.plivo.api.exceptions.PlivoValidationException; import com.plivo.api.models.base.ListResponse; class Session { public static void main(String[] args) { Plivo.init("", ""); try { SessionCreateResponse response = VerifySession.creator( "", "", "", "", "") .create(); System.out.println(response); } catch (PlivoRestException | IOException e) { e.printStackTrace(); } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 using System; using System.Collections.Generic; using Plivo; using Plivo.Exception; namespace dotnet_sdk { class Session { static void Main(string[] args) { // ENVIRONMENT var api = new PlivoApi("", ""); // Create Session try { Console.WriteLine("Create Session"); var response = api.VerifySession.Create(recipient:"",app_uuid:"",url:"",method:"POST",channel:""); Console.WriteLine(response); } catch (PlivoRestException e){ Console.WriteLine("Exception: " + e.Message); } } } } 1 2 3 4 5 6 7 8 9 10 curl -i --user auth_id:auth_token \ -H "Content-Type: application/json" \ -d '{ "app_uuid":"", "recipient": "", "url":"", "channel":"sms", "method":"POST" }' \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/ 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 package main import ( "fmt" "encoding/json" "github.com/plivo/plivo-go" ) func main() { client, err := plivo.NewClient("", "", &plivo.ClientOptions{}) if err != nil { fmt.Printf("Error:\n", err) } //Create Session response, err := client.VerifySession.Create( plivo.SessionCreateParams{ Recipient: "", AppUUID: "", Channel: "", URL: "", Method: "", }, ) if err != nil { fmt.Print("Error", err.Error()) return } res, _ := json.Marshal(response) fmt.Printf("Response: \n\n %#v \n", string(res)) } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Retrieve a session | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Retrieve a session** ---------------------- Retrieves a session. #### **API Endpoint** `GET` `https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/` ### **Arguments** No arguments need to be passed. ### **Returns** This API call returns the details for the session identified by the session\_uuid specified in the request URL. ### Response { "api_id": "abf7fc2b-fac5-471c-9592-74ed6834b5e6", "session_uuid": "60ea68db-b123-46d9-9eb2-1201d516dbbd", "app_uuid": "ec66515e-86f6-4507-8620-31c039538d7a", "recipient": "919380013443", "channel": "voice", "status": "Expired", "count": 3, "attempt_details": [\ {\ "channel": "voice",\ "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",\ "status": "answer",\ "time": "2023-06-01T08:52:39.363253Z"\ },\ {\ "channel": "sms",\ "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",\ "status": "delivered",\ "time": "2023-06-01T08:52:59.484375Z"\ },\ {\ "channel": "voice",\ "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",\ "status": "early media",\ "time": "2023-06-01T08:53:25.577153Z"\ }\ ], "charges": { "total_charge": "0.113", "validation_charge": "0.0000", "attempt_charges": [\ {\ "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",\ "channel": "voice",\ "charge": "0.03300"\ },\ {\ "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",\ "channel": "sms",\ "charge": "0.08000"\ },\ {\ "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",\ "channel": "voice",\ "charge": "0.00000"\ }\ ] }, "created_at": "2023-06-01T08:52:39.363253Z", "updated_at": "2023-06-01T08:53:25.577153Z" } ### Example Request 1 2 3 4 5 6 7 8 9 import sys sys.path.append("../plivo-python") import plivo client = plivo.RestClient() response = client.verify_session.get('') print(response) 1 2 3 4 5 6 7 8 9 10 11 12 require "rubygems" require "/usr/src/app/lib/plivo.rb" include Plivo #Environment api = RestClient.new("", "") begin puts("Get Session") response = api.verify_session.get('') puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 let plivo = require('plivo') let client = new plivo.Client('', ''); client.verify_session.get('').then(function(response) { let formattedResponse = JSON.stringify(response, null, 2); console.log(formattedResponse); }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ", ""); // Get a particular session detail try { $response = $client->verifySessions->get(''); print_r($response); } catch (Exception $ex) { print_r($ex); } ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 import java.io.IOException; import java.net.URL; import java.util.Collections; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.verify_session.VerifySession; import com.plivo.api.models.verify_session.SessionCreateResponse; import com.plivo.api.models.message.Message; import com.plivo.api.exceptions.PlivoValidationException; import com.plivo.api.models.base.ListResponse; class Session { public static void main(String[] args) throws PlivoValidationException { Plivo.init("", ""); // Get Session try { VerifySession response = VerifySession.getter("").get(); System.out.println(response); } catch (PlivoRestException | IOException e) { e.printStackTrace(); } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 using System; using System.Collections.Generic; using Plivo; using Plivo.Exception; namespace dotnet_sdk { class Session { static void Main(string[] args) { //ENVIRONMENT var api = new PlivoApi("", ""); //Get Session try { Console.WriteLine("Get Session Details"); var response = api.VerifySession.Get("", "", &plivo.ClientOptions{}) if err != nil { fmt.Printf("Error:\n", err) } //Get the details of a session response_get, err := client.VerifySession.Get(response.SessionUUID) if err != nil { fmt.Print("Error", err.Error()) return } res1, _ := json.Marshal(response_get) fmt.Printf("Response: \n\n %#v \n", string(res1)) } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Get Started Using Postman Collections for Plivo Voice APIs Get Started Using Postman Collections for Plivo Voice APIs ========================================================== Overview -------- Plivo APIs are packaged and ready to use with Postman, an API testing tool that helps developers set up, test, and explore APIs. Plivo’s Postman collection includes APIs for our SMS, Voice, Phone Numbers, Account, Lookup, and PHLO products, along with documentation for each API to help you learn about them. We’ve created a ready-to-use set of the applicable APIs so you don’t have to manually add endpoints that you’d like to use inside Postman. Each endpoint comprises all the available parameters and the necessary authentication process, along with example responses, so you only need to declare your credentials and parameter values globally to start exploring the features. Let’s walk through the process. Install Postman and download the Postman collection --------------------------------------------------- First, [download and install Postman](https://www.postman.com/downloads/) . You also need a Plivo account; if you don’t have one yet, [sign up](https://console.plivo.com/accounts/register/) now. Next, click on this button. A window will appear asking if you want the collection to be added to your local Postman app or if you want to use a web app. You’ll see the collection in your chosen space based on the options you’ve chosen. Add keys and tokens ------------------- Now you can add keys and tokens to your Postman collection. Open Postman from Applications under macOS or your desktop on Windows. First, add your authentication credentials. * Click on the collection `Plivo REST API`. ![Edit Details](https://docs.plivo.com/assets/posts/images/sms/quickstart/postman/setup.png) * Select `Authorization`, then, from the drop-down list, set the Type as Basic Auth. ![Set Authorization](https://docs.plivo.com/assets/posts/images/sms/quickstart/postman/authorization.png) * For `Username` and `Password`, fill in your Plivo Auth ID and Auth Token respectively, which you can find on the overview page of the [console](https://console.plivo.com/dashboard/) . You’ve now authenticated Postman to your Plivo account. The next step is to make that authentication available for every endpoint. #### Set up environment variables Set up the auth\_id as an environment variable, so you can use it in every endpoint you have. * Click on the collection `Plivo REST API`. ![Edit Details](https://docs.plivo.com/assets/posts/images/sms/quickstart/postman/setup.png) * Click on `Variables`. Declare the variable auth\_id, and provide the initial and current value as the Auth ID from the [console](https://console.plivo.com/dashboard/) . ![Set Variables](https://docs.plivo.com/assets/posts/images/sms/quickstart/postman/variable.png) * Once you’ve done that, you can access your Auth ID by writing `{{auth_id}}` within your Postman collection. We’ve already done that for you for all the APIs in the Plivo collection. **Now we’re ready to test some APIs!** Example: Make a phone call -------------------------- To see how Plivo and Postman work together, let’s start by making an outbound call. From the imported Plivo REST API collection, select the folder named `Call` and select the request to `make an outbound call`. Replace from with your caller\_id, to with the destination number you’d like to make a call, and answer\_url with a valid publicly accessible URL that returns a valid XML. These are the only mandatory parameters. **Note:*** The answer\_url updated in the collection returns a valid XML document, which means you just need to update the from and to fields to test the API. * You can replace the other optional parameters with meaningful values for your use case, or you can leave them out if you’re not using them in the request. To learn more about optional and required parameters, either refer to the documentation available within the Postman collection or visit our [Voice API reference guide](https://www.plivo.com/docs/voice/api/call/#make-a-call) . ![Document](https://docs.plivo.com/assets/posts/images/voice/quickstart/postman/document.png) You can also find an example API response and status code for each API directly beneath the API tab, as in this example: ![Successful example](https://docs.plivo.com/assets/posts/images/voice/quickstart/postman/example.png) Postman helps you keep all of your APIs organized, categorized, and always ready to use with just a few modifications. It helps not only with triggering API requests but also with [testing APIs](https://www.postman.com/api-platform/api-testing/) . Overall, Postman makes it easier for developers to test and integrate their systems with Plivo. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # List all sessions | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **List all sessions** --------------------- This API retrieves a list of sessions based on a filter criteria over the last 90 days. **Note:** The default rate limit for this API is 20 requests per minute. If the rate limit is exceeded, the API will throw the error “too many requests”. #### **API Endpoint** `GET` `https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/` ### **Arguments** | | | | --- | --- | | **app\_uuid string** | Filters results based on sessions sent using a specific application. | | **status string** | Filter results by the current status of a session. Allowed values: in-progress,verified,expired | | **recipient string** | Filters results by the number to which codes/OTPs were sent using Plivo APIs. You can filter the details by using the exact number in E.164 format — for example, +12025553434. | | **subaccount string** | Filters for sessions sent using a specific subaccount’s Auth Token. | | **limit string** | Denotes the number of results per page. The maximum number of results that can be fetched is 20.

Defaults to 20. | | **offset string** | Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about [offset-based pagination](https://www.plivo.com/docs/messaging/api/request#pagination)
. | | **session\_time string** | Filters sessions based on the time the session was initiated.

Timestamps are expected to be in YYYY-MM-DD HH:MM\[:ss\[.uuuuuu\]\] format, and are considered to be in UTC time zone.

If you do not specify this attribute, the sessions for the last 24 hours will be retrieved by default.

The filter can be used in five forms:

session\_time: Use this argument to filter for session by exact timestamp. The format expected is YYYY-MM-DD HH:MM:ss:uuuuuu. To get all sessions that were sent or received at 2021-03-21 11:47:30.982811, use session\_time=2021-03-21 11:47:30.982811
session\_time\_\_gt: gt stands for greater than. Use this argument to filter for sessions initiated after a given time. To get all session that were initiated after 2021-03-21 11:47, use session\_time\_\_gt=2021-03-21 11:47
session\_time\_\_gte: gte stands for greater than or equal to. To get all sessions that were initiated after or exactly at 2021-03-21 11:47\[:30\], use session\_time\_\_gte=2021-03-21 11:47\[:30\]
session\_time\_\_lt: lt stands for less than. Use this argument to filter for sessions initiated before a given time. To get all sessions that were initiated before 2021-03-21 11:47, use session\_time\_\_lt=2021-03-21 11:47
session\_time\_\_lte: lte stands for less than or equal to. To get all sessions that were initiated before or exactly at 2012-03-21 11:47\[:30\], use session\_time\_\_lte=2012-03-21 11:47\[:30\] | | **brand\_namestring** | Filters and lists all the sessions based on the specific brands that were passed in the session creation API. | | **app\_hashstring** | Filters and lists all the sessions based on the app hashes that were passed in the session creation API. | **Note:** **The subaccount filter is implicitly applied when a subaccount’s API credentials are used to fire this API. This argument should be used only when the parent account’s API credentials are used to fire this API.** ### **Returns** This API returns a list of sessions matching the filters specified in the request. The API response also contains a **meta** field with the fields: * **limit:** the size of the page returned in the response * **offset:** the offset for the page returned in the response * **next:** the URL that points to the next page of results * **previous:** the URL that points to the previous page of results ### Response { "api_id": "3a7a0d6d-1b85-4593-921c-373e673a5799", "meta": { "limit": 20, "offset": 0, "next": null, "previous": null }, "sessions": [\ {\ "session_uuid": "51e965f3-65a5-4ca0-9542-57154118a991",\ "app_uuid": "59728519-d145-45d6-8d46-60c06f7e8bbb",\ "recipient": "918681951370",\ "channel": "sms",\ "status": "expired",\ "count": 1,\ "attempt_details": [\ {\ "channel": "sms",\ "attempt_uuid": "bd460457-6c2f-4177-a879-e6a83c35d5a9",\ "status": "undelivered",\ "time": "2023-06-01T10:40:05.804031Z"\ }\ ],\ "charges": {\ "total_charge": "0.08",\ "validation_charge": "0.0000",\ "attempt_charges": [\ {\ "attempt_uuid": "bd460457-6c2f-4177-a879-e6a83c35d5a9",\ "channel": "sms",\ "charge": "0.08000"\ }\ ]\ },\ \ \ "created_at": "2023-06-01T10:40:05.804031Z",\ "updated_at": "2023-06-01T10:40:05.804031Z"\ },\ \ \ {\ "session_uuid": "60ea68db-b123-46d9-9eb2-1201d516dbbd",\ "app_uuid": "ec66515e-86f6-4507-8620-31c039538d7a",\ "recipient": "919380013443",\ "channel": "voice",\ "status": "expired",\ "count": 3,\ "attempt_details": [\ {\ "channel": "voice",\ "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",\ "status": "ANSWER",\ "time": "2023-06-01T08:52:39.363253Z"\ },\ {\ "channel": "sms",\ "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",\ "status": "delivered",\ "time": "2023-06-01T08:52:59.484375Z"\ },\ {\ "channel": "voice",\ "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",\ "status": "EARLY MEDIA",\ "time": "2023-06-01T08:53:25.577153Z"\ }\ ],\ "charges": {\ "total_charge": "0.113",\ "validation_charge": "0.0000",\ "attempt_charges": [\ {\ "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",\ "channel": "voice",\ "charge": "0.03300"\ },\ {\ "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",\ "channel": "sms",\ "charge": "0.08000"\ },\ {\ "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",\ "channel": "voice",\ "charge": "0.00000"\ }\ ]\ },\ "created_at": "2023-06-01T08:52:39.363253Z",\ "updated_at": "2023-06-01T08:53:25.577153Z"\ } \ ] } ### Example Request 1 2 3 4 5 6 7 8 9 10 11 import sys sys.path.append("../plivo-python") import plivo client = plivo.RestClient() response = client.verify_session.list( limit=2, offset=6) print(response) 1 2 3 4 5 6 7 8 9 10 11 12 require "rubygems" require "/usr/src/app/lib/plivo.rb" include Plivo #Environment api = RestClient.new("", "") begin puts("List all Sessions") response = api.verify_session.list(limit:1,offset:0) puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 let plivo = require('plivo') let client = new plivo.Client('', ''); client.verify_session.list().then(function(response) { let formattedResponse = JSON.stringify(response, null, 2); console.log(formattedResponse) }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 ", ""); // List all sessions try { $response = $client->verifySessions->list(['limit' => '5','offset' => 0]); print_r($response); } catch (Exception $ex) { print_r($ex); } ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 import java.io.IOException; import java.net.URL; import java.util.Collections; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.verify_session.VerifySession; import com.plivo.api.models.verify_session.VerifySessionList; import com.plivo.api.models.verify_session.SessionCreateResponse; import com.plivo.api.models.message.Message; import com.plivo.api.exceptions.PlivoValidationException; import com.plivo.api.models.base.ListResponse; class Session { public static void main(String[] args) throws PlivoValidationException { Plivo.init("", ""); try { ListResponse response = VerifySession.lister() .limit(1) .offset(0) .list(); System.out.println(response); } catch (Exception e) { e.printStackTrace(); } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 using System; using System.Collections.Generic; using Plivo; using Plivo.Exception; namespace dotnet_sdk { class Session { static void Main(string[] args) { // ENVIRONMENT var api = new PlivoApi("", ""); // List all Sessions try { Console.WriteLine("List all Sessions"); var response = api.VerifySession.List(limit:1,offset:0); Console.WriteLine(response); } catch (PlivoRestException e) { Console.WriteLine("Exception: " + e.Message); } } } } 1 2 curl -i --user auth_id_ID:auth_token \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/ 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 package main import ( "fmt" "encoding/json" "github.com/plivo/plivo-go" ) func main() { client, err := plivo.NewClient("", "", &plivo.ClientOptions{}) if err != nil { fmt.Printf("Error:\n", err) } //List details of all sessions for the account with filter params response_list, err := client.VerifySession.List( plivo.SessionListParams{ Limit: 1, Offset:2, }, ) if err != nil { fmt.Print("Error", err.Error()) return } res2, _ := json.Marshal(response_list) fmt.Printf("Response: \n\n %#v \n", string(res2)) } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Validate a session | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Validate a session** ---------------------- This API validates a session. #### **API Endpoint** `POST` `https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/` ### **Arguments** | | | | --- | --- | | **otp stringrequired** | The OTP that you want to validate against a particular session. | ### **Returns** Returns a JSON response containing the API request ID and session UUID. ### Response { "api_id": "e7af31b5-a7cb-40d6-a3ab-122fdcc9f0fe", "message": "session validated successfully.", } ### Example Request 1 2 3 4 5 6 7 8 9 10 11 import sys sys.path.append("../plivo-python") import plivo client = plivo.RestClient('','') response = client.verify_session.validate( session_uuid = '', otp='') print(response) 1 2 3 4 5 6 7 8 9 10 11 12 require "rubygems" require "/usr/src/app/lib/plivo.rb" include Plivo #Environment api = RestClient.new("", "") begin puts("Validate Session") response = api.verify_session.validate('','') puts response rescue PlivoRESTError => e puts 'Exception: ' + e.message end 1 2 3 4 5 6 7 let plivo = require('plivo') let client = new plivo.Client('', ''); client.verify_session.validate({id:'',otp:''}).then(function(response) { console.log(response) }).catch(function (error) { console.log(error) }); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 ", ""); //Validate Session try { $response1 = $client->verifySessions->validate( '', '' ); print_r($response1); } catch (Exception $ex) { print_r($ex); } ?> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 import java.io.IOException; import java.net.URL; import java.util.Collections; import com.plivo.api.Plivo; import com.plivo.api.exceptions.PlivoRestException; import com.plivo.api.models.verify_session.VerifySession; import com.plivo.api.models.verify_session.VerifySessionList; import com.plivo.api.models.verify_session.SessionCreateResponse; import com.plivo.api.models.message.Message; import com.plivo.api.exceptions.PlivoValidationException; import com.plivo.api.models.base.ListResponse; class Session { public static void main(String[] args) throws PlivoValidationException { Plivo.init("", ""); try { SessionCreateResponse response = VerifySession.validation( "", "") // Validation .create(); System.out.println(response); } catch (Exception e) { e.printStackTrace(); } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 using System; using System.Collections.Generic; using Plivo; using Plivo.Exception; namespace dotnet_sdk { class Session { static void Main(string[] args) { // ENVIRONMENT var api = new PlivoApi("", ""); // Validate Session try { Console.WriteLine("Validate Session"); var response = api.VerifySession.Validate(session_uuid:"",otp:""); Console.WriteLine(response); } catch (PlivoRestException e) { Console.WriteLine("Exception: " + e.Message); } } } } 1 2 3 4 5 6 curl -i --user auth_id:auth_token \ -H "Content-Type: application/json" \ -d '{ "OTP": "" }' \ https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/ 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 package main import ( "fmt" "encoding/json" "github.com/plivo/plivo-go" ) func main() { client, err := plivo.NewClient("", "", &plivo.ClientOptions{}) if err != nil { fmt.Printf("Error:\n", err) } //Validate response_validate, err := client.VerifySession.Validate( plivo.SessionValidationParams{ OTP: "", }, "", ) if err != nil { fmt.Print("Error", err.Error()) return } res3, _ := json.Marshal(response_validate) fmt.Printf("Response Validation: \n\n %#v \n", string(res3)) } Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Migrate from Twilio to the Plivo Voice API | Plivo Technical Guide: Migrating from Twilio to Plivo =============================================== Introduction ------------ Migrating from Twilio to Plivo is a painless process. The two companies’ API structures, implementation mechanisms, XML structure, SMS message processing, and voice call processing are similar. We wrote this technical comparison between Twilio and Plivo APIs so that you can scope the code changes for a seamless migration. Understanding the differences between Twilio and Plivo development ------------------------------------------------------------------ Most of the APIs and features that are available on Twilio are also available on Plivo, and the implementation mechanism is easier as the steps involved are almost identical. This table gives a side-by-side comparison of the two companies’ features and APIs. An added advantage with Plivo is that not only can you code using the familiar API/XML coding method, you can also implement your use cases using [PHLO](/docs/phlo/) (Plivo High Level Objects), a visual workflow builder that lets you create workflows by dragging and dropping components onto a canvas — no coding required. | | | | | | | --- | --- | --- | --- | --- | | **Features and APIs** | **Twilio** | **Plivo** | **Similarities** | **Implementation Interface** | | [Voice API](https://plivo.com/docs/voice/)
: Make phone calls | ✅ | ✅ | Request and response variables’ structure | API
PHLO | | [Programmatically manage call flows](/docs/voice/concepts/overview/#controlling-calls-programmatically) | Twiml | Plivo XML | XML element and its attributes structure | XML
PHLO | | [Geo Permissions](/docs/voice/concepts/geo-permissions/) | ✅ | ✅ | Feature parity | Console | | [Number Lookup API](/docs/lookup/) | ✅ | ✅ | API Parity | API | | [Phone number management](/docs/numbers/) | ✅ | ✅ | Feature parity | API
Console | | [Call Insights](/docs/voice/call-insights/) | ✅ | ✅ | Feature parity | Console | | [Validating Requests](/docs/voice/concepts/signature-validation/) | ✅ | ✅ | Feature parity | API
XML | | Subaccounts | ✅ | ✅ | Feature parity | API | | [Speech recognition](/docs/voice/use-cases/receive-input/node/#detect-speech-inputs) | ✅ | ✅ | Feature parity | XML | | [SSML](/docs/voice/concepts/ssml/)
(Speech Synthesis Markup Language) | ✅ | ✅ | Feature parity | XML
PHLO | | [Browser](/docs/sdk/client/browser/overview/)
and [Mobile](/docs/sdk/client/ios/overview/)
SDKs | ✅ | ✅ | Feature parity | [Browser](/docs/sdk/client/browser/overview/)

[Android](/docs/sdk/client/android/overview/)

[iOS](/docs/sdk/client/ios/overview/) | | [Transcription](/docs/voice/xml/record/) | ✅ | ✅ | Feature parity | API
XML
PHLO | | [Custom SIP Headers](/docs/voice/use-cases/pass-custom-headers/node/) | ✅ | ✅ | Feature parity | API
XML
PHLO
Browser SDK
Mobile SDKs | | [HTTP callbacks](/docs/voice/concepts/callbacks/) | ✅ | ✅ | Feature parity | API
XML
PHLO | Create a Plivo account ---------------------- Start by [signing up for a free trial account](https://console.plivo.com/accounts/register/) that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can [add more](https://console.plivo.com/payments/) as you go along. You can also [add a phone number](https://console.plivo.com/phone-numbers/search/) to your account, or [port a number from Twilio to Plivo](#porting-your-existing-numbers-from-twilio-to-plivo) , to start testing the full range of our voice and SMS features. A page in our support portal [walks you through the signup process](https://support.plivo.com/hc/en-us/articles/360041203772) . Migrate your voice application ------------------------------ To migrate an existing application from Twilio to Plivo using APIs, follow the voice quickstart guides for one of the seven languages Plivo provides SDKs for: [PHP](/docs/messaging/quickstart/php-laravel/) , [Node.js](/docs/messaging/quickstart/node-expressjs/) , [C# (.NET)](/docs/messaging/quickstart/dotnet-framework/) , [Java](/docs/messaging/quickstart/java-spring/) , [Python](/docs/messaging/quickstart/python-flask/) , [Ruby](/docs/messaging/quickstart/ruby-rails/) , and [Go](/docs/messaging/quickstart/go-gin/) . For another alternative that lets you evaluate Plivo’s SMS APIs and their request and response structure, use our [Postman collections](/docs/voice/quickstart/postman/) . ### How to make an outbound call Let’s take a look at the process of refactoring the code to migrate your app from Twilio to Plivo to set up a simple Python application to make an outbound call by changing just a few lines of code. | | | | --- | --- | | **Twilio** | **Plivo** | | import os
from twilio.rest import Client
account_sid = os.environ[""]
auth_token = os.environ[""]
client = Client(account_sid, auth_token)

call = client.calls.create(
to='+14155551212',
from_='+14165553434',
url='https://demo.twilio.com/docs/voice.xml'
)

print(call) | import os, plivo

auth_id = os.environ[""]
auth_token = os.environ[""]
client = plivo.RestClient(auth_id, auth_token)

call = client.calls.create(
to_='+14155551212',
from_='+14165553434',
answer_url='https://s3.amazonaws.com/static.plivo.com/answer.xml',
)
print(call) | Replace the authentication placeholders with authentication credentials from the Twilio or [Plivo console](https://console.plivo.com/dashboard/) . Alternatively, you can implement the same functionality using one of our [PHLO templates](https://console.plivo.com/phlo/list/) . To make an outbound call, you can create a PHLO like this: ![Create a PHLO for outbound calls](https://docs.plivo.com/assets/dist/images/v2/phlo/outbound_call_phlo.gif) ### How to receive an incoming call You can migrate an application for receiving and handling an incoming call from Twilio to Plivo just as seamlessly, as in this example: | | | | --- | --- | | **Twilio** | **Plivo** | | from flask import Flask
from twilio.twiml.voice_response import VoiceResponse

app = Flask(__name__)

@app.route("/receive_call", methods=['GET', 'POST'])
def receive_call():
"""Respond to incoming phone calls with a 'Hello world' message"""
# Start our TwiML response
resp = VoiceResponse()

# Read a message aloud to the caller
resp.say("Hello, world!", voice='alice')

return str(resp)

if __name__ == "__main__":
app.run(debug=True) | from flask import Flask, request, make_response
from plivo import plivoxml

app = Flask(__name__)

@app.route('/receive_call', methods=['GET','POST'])
def receive_call():
# Generate a Speak XML element with the details of the text to play on the call
response = (plivoxml.ResponseElement()
.add(plivoxml.SpeakElement('Hello, world!')))
return(response.to_string())

if __name__ == "__main__":
app.run(host='0.0.0.0', debug=True) | Here again you can implement the same functionality using one of our [PHLO templates](https://console.plivo.com/phlo/list/) : ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/receive_call-phlo.gif) ### How to forward an incoming call You can migrate an application for forwarding an incoming call from Twilio to Plivo as in this example: | | | | --- | --- | | **Twilio** | **Plivo** | | from flask import Flask
from twilio.twiml.voice_response import Dial, VoiceResponse, Say

app = Flask(__name__)

@app.route("/forward_call", methods=['GET', 'POST'])
def forwardcall():
"""Forward incoming phone call to connect the caller to another party"""

# Start our TwiML response
response = VoiceResponse()

# Dial verb to forward the call
response.dial('202-555-1234')
response.say('Goodbye')

return str(response)

if __name__ == "__main__":
app.run(debug=True) | from flask import Flask, request, make_response, Response
from plivo import plivoxml

app = Flask(__name__)

@app.route('/forward_call', methods=['GET', 'POST'])
def forwardcall():

response = plivoxml.ResponseElement()
response.add(
plivoxml.DialElement().add(
plivoxml.NumberElement('12025551234')))
return(response.to_string())

if __name__ == '__main__':
app.run(host='0.0.0.0', debug=True) | Here again you can implement the same functionality using one of our [PHLO templates](https://console.plivo.com/phlo/list/) : ![Create a PHLO to receive incoming call](https://docs.plivo.com/assets/dist/images/v2/phlo/callforward.gif) For more information about migrating your voice applications to Plivo, check out our [detailed use case guides](/docs/voice/use-cases/make-outbound-calls/node/) , available for all seven programming languages and PHLO. ### More use cases You can migrate applications that serve other use cases too: * [Phone system IVR — Touch-Tone/DTMF-based virtual assistant](/docs/voice/use-cases/ivr/node/) * [Voice-controlled virtual assistant](/docs/voice/use-cases/receive-input/node/#detect-speech-inputs) * [Number masking](/docs/voice/use-cases/number-masking/node/) * [Supervisor coaching](/docs/voice/use-cases/supervisor-coaching/node/) * [PINless conference](/docs/voice/use-cases/call-conference/node/) * [Conference with PIN](/docs/voice/use-cases/conference-with-pin/node/) * [Voicemail](/docs/voice/use-cases/voicemail/node/) * [Voice alerts broadcasting](/docs/voice/use-cases/voice-broadcasting/node/) * [Voice survey](/docs/voice/use-cases/voice-survey/node/) * [Dial status reporting](/docs/voice/use-cases/dial-status-reporting/node/) * [Screen incoming calls](/docs/voice/use-cases/screen-incoming-calls/node/) * [Record a call](/docs/voice/use-cases/screen-incoming-calls/node/) Port your existing numbers from Twilio to Plivo ----------------------------------------------- If you want to continue using your phone numbers from Twilio, you can port the numbers to Plivo without having any downtime on your services for your customers. Phone number porting must be requested by a phone number’s owner. Here’s an overview of the process for porting a phone number to Plivo: 1. Phone number’s owner submits porting request with documentation. 2. Plivo verifies the porting request. 3. Plivo submits porting request to the gaining carrier. 4. The gaining carrier submits porting request to the losing carrier. 5. The losing carrier responds with an approval or a rejection. 6. Plivo notifies phone number owner of Firm Order Commitment or porting date. You can check our [number porting guide](/docs/numbers/number-porting/) to initiate the process. Rent new phone numbers for your migrated app -------------------------------------------- You can rent new phone numbers on the Plivo platform for your migrated applications as well. Plivo provides a self-serve [console](https://console.plivo.com/active-phone-numbers/) to rent new numbers and to manage them. You can also use the [Phone Numbers API](/docs/numbers/api/overview/) for number management. Our [Phone Numbers quickstart guide](/docs/numbers/guides/buy-a-number/) provides more information. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Voice Overview | Plivo Docs Overview ======== Plivo’s voice API platform lets you integrate voice calling into your applications. With it, you can make, receive, and control calls across the world. Plivo offers a rich set of programmatic building blocks that you can use to add voice communication to your existing products and workflows. With Plivo’s APIs and SDKs, you can: * Make phone calls to any phone number in the world. * Receive phone calls on virtual phone numbers purchased through Plivo. * Make internet calls to and from IP endpoints connected through Plivo’s Browser, iOS, and Android SDKs, or through third-party softphone clients. * Control the experience on connected calls in real time using Plivo XML elements and APIs to perform actions such as playing a prompt or dialing and connecting a call to another number. What is a voice call? --------------------- A voice call involves two-way conversation between two or more users. Plivo acts as the intermediary to connect these users. Devices that may be involved in a voice call include not only mobile, landline, and VoIP phones, but also browser and mobile apps. Call legs --------- For voice calls on the Plivo voice platform, multiple call legs may be involved, depending on the call flow, and each call leg is considered a separate call. For example, in a call forwarding use case, the inbound connection between the caller and the Plivo voice platform is considered the A leg, and the outbound connection between the Plivo voice platform and the destination is the B leg. Types of calls -------------- Plivo supports outbound, inbound, and forwarded calls. Here’s a look at how each works. ### Outbound API calls ![Outbound API call](https://docs.plivo.com/assets/posts/images/voice/overview/outbound_call.svg) 1. Your application uses Plivo’s voice API to make an outbound call. Outbound API call requests are queued and processed at two calls per second. 2. Plivo makes a call to a destination number. 3. Plivo notifies your application server as soon as the call is answered. 4. Plivo handles the call based on the XML returned by the application server. ### Inbound calls to Plivo phone numbers ![Inbound calls to Plivo number](https://docs.plivo.com/assets/posts/images/voice/overview/Inbound_pstn_call.svg) 1. Someone calls your Plivo phone number. 2. Plivo notifies your application server about the call. 3. Plivo handles the call based on the XML returned by the application server. ### Forwarded calls ![Forwarded calls](https://docs.plivo.com/assets/posts/images/voice/overview/call_forwarding.svg) 1. Someone calls your Plivo phone number. 2. Plivo notifies your application server about the call. 3. Plivo handles the call based on the XML returned by the application server. In this case, the application server returns a Dial XML element with instructions to forward the call to another number. 4. Plivo initiates a call to the phone number or SIP endpoint specified in the Dial XML. 5. Once the call is answered, the two parties are connected. **Note:** There are two distinct call legs involved in this call flow. 1. A leg: The inbound call connection from the caller to Plivo. 2. B leg: The outbound call from Plivo to the destination specified in the Dial XML. ### Inbound IP calls from browsers and mobile apps ![Outbound calls from Browser App](https://docs.plivo.com/assets/posts/images/voice/overview/outbound_call_browsers.svg) 1. A browser or mobile app initiates a call to Plivo. 2. Plivo notifies your application server about the call. 3. Plivo handles the call based on the XML returned by the application server. In this case, the application server returns a Dial XML element with instructions to connect the call with a specified phone number. 4. Plivo initiates a call to the phone number specified in the Dial XML. 5. Once the call is answered, the two parties are connected. **Note:** There are two distinct call legs involved in this call flow. 1. A leg: The internet call between the browser or mobile app and Plivo. These types of calls are categorized as “Client SDK (browser, mobile) and SIP calls” on our [pricing page](https://www.plivo.com/voice/pricing/) . 2. B leg: The outbound call from Plivo to the destination specified in the Dial XML. Controlling calls programmatically ---------------------------------- Plivo XML lets you programmatically provide Plivo with instructions to control outbound and inbound calls. Once a call is answered, Plivo invokes a specified URL to request an XML document to be used to process the call. Plivo provides [XML elements](/docs/voice/xml/response/) to handle call flow synchronously and to perform actions such as * Playing music while a caller is on hold. * Reading out specified text to a caller. * Accepting numeric and speech input. * Dialing and connecting to another number. ### How to control outbound API calls with Plivo XML An application can initiate an outbound call through an API request to Plivo. When  the call is answered, Plivo invokes the application service endpoint given in the `answer_url` API request parameter, which carries instructions to control the call. For example, you could return a [Speak XML](/docs/voice/xml/speak/) or [Play XML](/docs/voice/xml/play/) element to play a prompt when the call is answered. ![Outbound Call](https://docs.plivo.com/assets/posts/images/voice/overview/outbound_call.svg) ### How to control incoming calls with Plivo XML When someone dials a Plivo phone number, the `answer_url` parameter configured for the Plivo application associated with the number is triggered. Details about the incoming call, such as the from and to numbers, are included in the request to the  `answer_url`. You can control internet calls initiated by Plivo endpoints (from browser and mobile apps) in the same way. These calls invoke the `answer_url` of the Plivo application associated with the endpoint. ![Incoming calls](https://docs.plivo.com/assets/posts/images/voice/overview/incoming_calls.svg) ### Asynchronous call management with Plivo’s REST APIs By using Plivo’s REST APIs, you can asynchronously manage calls by setting API requests to perform various actions on ongoing calls. These actions include playing an audio file, playing a text-to-speech message, recording calls and conferences, and transferring calls. Call management features ------------------------ Here are some basic call management examples to help you learn about Plivo’s XML and API capabilities, and see how to use Plivo to manage call flows. ### Play a prerecorded audio or text-to-speech prompt * Use the [Play XML element](/docs/voice/xml/play/) to play a prerecorded MP3 or WAV audio file on the call. https://s3.amazonaws.com/plivocloud/Trumpet.mp3 * Use the [Speak XML element](/docs/voice/xml/speak/) to play a text-to-speech prompt on an ongoing call. This is useful for instances in which you dynamically change the prerecorded message for each call. Go Green, Go Plivo. * You can use [SSML](/docs/voice/concepts/ssml/) to control the pronunciation, pitch, volume, and other aspects of the machine voice generated by Plivo. Hello and welcome to the Plivo text to speech engine. We are now testing the SSML feature. * Use the [Play API](/docs/voice/api/call/play-audio-on-calls/) to play an audio file (MP3 or WAV format), or use the [Speak API](/docs/voice/api/call/speak-text-on-calls/) to play spoken versions of text, on an ongoing call asynchronously — for example, to play notifications to users waiting on a call. ### Build an interactive voice response system * You can use the [GetInput XML element](/docs/voice/xml/getinput/) to build an interactive voice response (IVR) system that prompts callers for input, then responds based on keys pressed by the caller. Press 1 to schedule an appointment. Press 2 to cancel an existing appointment. * You can also use the GetInput element to collect speech inputs from callers in real time. Plivo’s [automatic speech recognition](https://www.plivo.com/voice/automatic-speech-recognition/) (ASR) engine instantly transcribes the caller’s speech into text, so you can build intelligent systems that respond based on what a caller speaks. Say New Appointment to schedule an appointment. Say Cancel Appointment to cancel an existing appointment. ### Call forwarding Call forwarding lets you dynamically route incoming calls to available agents, extensions, or departments. You can use the [Dial XML element](/docs/voice/xml/dial/) to forward a call to a number or to a Plivo endpoint on a browser or iOS or Android app. You can use the Dial element for call hunting or to attempt to connect to multiple numbers or endpoints. This response, for instance, connects a caller to the first number or endpoint that answers the call. sip:alice1234@phone.plivo.com 12025551111 sip:john1234@phone.plivo.com ### Conferences and multiparty calls The [Conference XML element](/docs/voice/xml/conference/) hosts a conference call to which multiple participants can be added at the same time. Plivo conferences offer a wide array of features and cater to a variety of [use cases](/docs/voice/use-cases/conference-with-pin/node/) involving multiple participants. Explore all the features that conferences provide in our [Conference API](/docs/voice/api/conference/) and [Member API](/docs/voice/api/conference/member/) reference pages. You can also use the Conference element to create waiting rooms for callers before connecting them with an available agent. My Room ### Recording calls * You can record all or part of an ongoing call asynchronously using Plivo’s [Record API](/docs/voice/api/call/record-calls/) , and record ongoing conference calls using the [Record Conference API](/docs/voice/api/conference/record-conference/) . * You can record a complete call session or implement virtual voice mail boxes using the [Record XML element](/docs/voice/xml/record/) . 12025551111 * Recordings are securely stored on the Plivo platform. You can access or delete recordings at any time by using the [retrieve recording API](/docs/voice/api/recording/#retrieve-a-recording) and [delete recording API](/docs/voice/api/recording/#delete-a-recording) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Verify Status Callbacks | Plivo API Reference Latest Legacy * [Python](#tab-python) * [Ruby](#tab-ruby) * [Node](#tab-js) * [PHP](#tab-php) * [Java](#tab-java) * [.NET](#tab-net) * [Go](#tab-go) * [cURL](#tab-curl) **Verify Status Callbacks** --------------------------- The best way to keep track of the status of your Verify sessions is to set up a server endpoint to receive status update events in real-time. Once you’ve configured this endpoint, specify its URL and HTTP method in the [create a verify session](/docs/verify/api/session/create-a-session/) request. Plivo will call this endpoint with the latest Verify session details as and when the session status changes. ### **Attributes** With every status change event, these message attributes are passed to the status update URL. They’re passed as form data if the method configured is POST, and as query parameters if it’s GET. | | | | --- | --- | | **AttemptSequence string** | This indicates the sequence of the verification attempt for which you are receiving this callback. | | **AttemptUUID string** | This is the unique identifier for the SMS that was sent or Voice call that was triggered as part of the Verify session. | | **Channel string** | The channel you used to send the code.

Possible values: sms,voice | | **ChannelErrorCode string** | This is the error code returned by the channel on which verification was attempted. | | **ChannelStatus string** | This indicates the status of your verification request based on the specified channel. Possible values:

sms - queued, sent, undelivered, failed, delivered

voice - in-progress, completed, ringing | | **Recipient string** | The phone number to which the message is to be delivered. | | **RequestTime string** | UTC time when this attempt was created. | | **SessionStatus string** | The current status of the session.

Possible values: in-progress and expired. | | **SessionUUID string** | A 36-character string that uniquely identifies a session detail record. | Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Plivo Docs - iOS SDK v2 for VoIP | Plivo Plivo iOS SDK ============= The Plivo iOS SDK v2 allows you to make outgoing and receive incoming calls in your iOS application. It supports Pushkit and Callkit, hence eliminating the need for persistent connections to receive incoming calls. The SDK currently supports iOS versions 8 and above, including iOS 12. It supports both IPv4, IPv6 networks for performing inbound and outbound calls. #### Incoming Voice Call ![Notification Service](https://docs.plivo.com/assets/images/interacting-with-push-notification-service.svg) #### Outgoing Voice Call ![External Carriers](https://docs.plivo.com/assets/images/interacting-with-external-carriers.svg) Prerequisites ------------- 1. [Register](https://console.plivo.com/accounts/register/) for a Plivo account. You need a Plivo account to create endpoints and PHLO. 2. Plivo Endpoint: An endpoint facilitates making and receiving calls from the iOS client. For more information on what an endpoint is and where it can be used, see [the endpoint tutorial](/docs/voice/concepts/sip-endpoint/) . Create an endpoint as required. You can automate the creation of endpoints if required using our REST API. Please refer to our [API documentation for endpoint](/docs/voice/api/endpoint/) for more details. 3. Xcode IDE: Download the latest version of Xcode IDE from [https://developer.apple.com/xcode/ide/](https://developer.apple.com/xcode/ide/) 4. Apple Developers certificate: It is required for testing the app on an actual device. You do not need the certificate if you plan to test the application on a simulator. 5. PHLO: Plivo High-Level Object (PHLO) is a collaborative way of building and deploying apps visually. You must create a [PHLO](/docs/sdk/client/ios/v2/phlo-to-endpoint/) and link it with your endpoint. Getting started --------------- To create a VoIP enabled iOS app 1. Install [Cocoapods](https://cocoapods.org/pods/PlivoVoiceKit) and add the PlivoVoiceKit framework. 2. Use our [iOS quickstart Application](https://github.com/plivo/plivo-ios-quickstart-app) as a starting point to create your app. 3. Refer to [iOS SDK reference](/docs/sdk/client/ios/reference/) for more information on creating applications capable of making and receiving calls in your iOS app. 4. To set up incoming calls with push notifications, see [Setting up Push credentials](/docs/sdk/client/concepts/mobile/setting-up-push-credentials/) . 5. Manage Apple Push credentials on the console, see [Manage Push Credentials](/docs/sdk/client/concepts/mobile/manage-push-credentials/) . 6. Use our [Best practices guide](/docs/sdk/client/concepts/mobile/best-practices/) to build the iOS app efficiently. 7. To debug the basic call related issues, see [Troubleshooting guide](/docs/sdk/client/troubleshooting-guide/) Resources --------- 1. [Create applications capable of making and receiving calls in your iOS app using Cocoapods](https://cocoapods.org/pods/PlivoVoiceKit) 2. [Make outgoing and receive incoming calls in your iOS application using our quickstart example app](https://github.com/plivo/plivo-ios-quickstart-app) 3. [Download the latest Plivo iOS SDK package](https://helpers.plivo.com/ios/plivo-ios-package-2.0.zip) 4. [Create applications capable of making and receiving calls in your iOS app using our iOS SDK Reference](/docs/sdk/client/ios/reference/) 5. [Receive incoming calls on the Plivo iOS SDK v2 using pushkit](/docs/sdk/client/concepts/mobile/setting-up-push-credentials/) 6. [Managing Endpoint calls using PHLO](/docs/sdk/client/ios/v2/phlo-to-endpoint/) Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Voice Terminology | Plivo Docs Terminology =========== | | | | --- | --- | | A leg | An A leg is the initial leg of a call. When someone dials your Plivo number, the inbound call connection between the caller and your Plivo number is the A leg. For more information about call legs and types of calls, refer to our [Voice Overview](/docs/voice/concepts/overview/#what-is-a-voice-call)
page. | | API | An application programming interface is a computing interface that defines interactions between multiple software intermediaries. | | api\_id | A Plivo api\_id is a unique ID for each API request made. | | B leg | The B leg represents the secondary leg of a call. For example, if an inbound call to your Plivo number is forwarded to another line, the forwarded leg is the B leg. For more information about call legs and types of calls, refer to our [Voice Overview](/docs/voice/concepts/overview/#what-is-a-voice-call)
page. | | Carrier | A telecom carrier is a company that’s authorized by regulatory agencies to operate a telecommunications system and provide mobile or landline connections to consumers and businesses. | | CDR | A Call Detail Record contains all the details about and serves as the source of truth for that call. You can export CDRs from Voice > Logs > [Calls](https://console.plivo.com/voice/logs/calls/)
on the Plivo console. | | Client SDK | Plivo’s client software development kits contain wrapper classes that help you connect directly to the Plivo Voice Platform to make and receive calls using a Plivo endpoint or client. Plivo provides [Browser](/docs/sdk/client/browser/overview/)
and mobile ([iOS](/docs/sdk/client/ios/overview/)
and [Android](/docs/sdk/client/android/overview/)
) client SDKs that you can integrate with your web and mobile apps to enable voice calling. | | DID | Direct Inward Dial numbers are virtual phone numbers that Plivo provides and on which you can receive calls. You can programmatically control calls coming in to these numbers by assigning a Plivo application to them using the Plivo console. For more information, refer to our [Receive Incoming Calls](/docs/voice/use-cases/receive-incoming-calls/node/)
guide. | | DTMF | Dual-tone multi-frequency tones, also called Touch-Tone, are the tones produced when someone presses a telephone keypad. DTMF tones are collected from users and passed over a communications network to a destination for processing. DTMF inputs are useful for IVR systems and use cases that involve user-directed interaction. | | Hardphone | A hardphone is a hardware-based IP phone from vendors such as Cisco, Polycom, Mitel, and Snom | | IVR | Interactive voice response systems let phone systems route calls without operator intervention. They depend on users speaking or entering keypad presses to traverse a menu of choices. | | PoP | A point of presence is an access point that connects communication networks. PoPs are often located near large Internet exchange points (IXP) to minimize latency and maximize available bandwidth. Plivo maintains seven PoPs strategically placed across four continents to ensure optimal voice quality. | | PSTN | The public switched telephone network is the circuit-switched telephone network that has been in use since the 1800s. It comprises telephone lines, fiber optic cables, microwave transmission links, cellular networks, communications satellites, and undersea telephone cables, all interconnected by switching centers. It’s also referred to as POTS — plain old telephone service. By contrast, VoIP uses packet switching. | | Routing | Routing, in telephony, is the process of selecting the priority carrier for a given destination prefix and country. | | Sandbox number | Sandbox numbers are number that have been verified for use with Plivo. You must use a sandbox number to make a call or send a message if you have a Plivo trial account. | | SDK | A software development kit is a package of prewritten code that developers can reuse to minimize the amount of unique code they need to develop themselves. | | Server SDK | Plivo’s server software development kits help developers quickly integrate their code with Plivo APIs in their language of choice. They contains functions and methods that can be used to trigger API requests and generate XML to manage call flows and implementations. Plivo provides server SDKs for seven languages: [PHP](/docs/voice/quickstart/php/)
, [Python](/docs/voice/quickstart/python-flask/)
, [Node.js](/docs/voice/quickstart/node-expressjs/)
, [Java](/docs/voice/quickstart/java-spring/)
, [.NET (C#)](/docs/voice/quickstart/dotnet-framework/)
, [Ruby](/docs/voice/quickstart/ruby-rails/)
, and [Go](/docs/voice/quickstart/go-gin/)
. | | SIP | Session Initiation Protocol is a signaling protocol for controlling and signaling multimedia communication on VoIP networks. | | SIP URI | A SIP URI (uniform resource identifier) is an address for a SIP-enabled device. SIP URIs are written in the format user@domain.tld. | | Softphone | A softphone is a software-based implementation of a SIP phone client. Examples: Zoiper, Bria, X-Lite | | UUID | A universally unique identifier — a 128-bit label, calculated using standard formulas in such a way that the probability of having duplicate UUIDs is negligible. Plivo uses UUIDs to identify various entities, including individual calls, messages, and API requests. | | VoIP | Voice over Internet Protocol, also called IP telephony, is a set of methods and technologies for the delivery of voice and multimedia communications over packet-switched IP networks such as the internet. | | WebRTC | Web Real-Time Communication is a World Wide Web Consortium (W3C) specification that allows audio and video communication to work inside web pages and supports browser-to-browser applications for voice calling, video chat, and P2P file sharing without the need for plugins. | | XML | Extensible Markup Language defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. Plivo uses XML documents to control communication flows. | Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Voice Features | Plivo Docs Features ======== Here are some of the key features Plivo’s Voice API platform supports. Call queueing ------------- Make multiple calls with a single API request. We handle call queuing for you so you don’t have to worry about building the workflow yourself. By default, all your calls get queued on the Plivo platform in sequential order, and are initiated according to the CPS (calls per second) set for your account. Global conference calling ------------------------- Integrate multiparty calls and audio conferencing into your applications, or build advanced contact center functionality. Plivo provides conference APIs, conference XML, and multiparty calls using [PHLO](/phlo/) ’s wide array of features that help you integrate your contact center and calls from anywhere across the globe. Text to speech -------------- Speak dynamic text in 28 accents across various languages. Choose from an array of SSML voices powered by Amazon Polly. Play audio prompts ------------------ Play prerecorded audio files at any time during a call. Create prompts, announcements, or music on hold. Dual-channel call recording --------------------------- Record, store, and retrieve calls at any time. Recordings are dual-channel by default and stored encrypted. Get digit input (DTMF) ---------------------- Collect digits from a user’s keypad during a call and control your call flow based on those inputs. Speech recognition ------------------ Build intelligent voice-driven interactions, including conversational IVR and form fills. Automatically recognize speech as text on your voice calls in real time. Answering machine detection --------------------------- Detect whether an outbound voice call was answered by a human or an answering machine. Leave a voicemail message if the call is answered by an answering machine and connect the call to an agent if it’s answered by a human. Voicemail transcription ----------------------- Never listen to another voicemail message — read them instead. Our premium voicemail transcriptions are real-time, high quality, and very accurate. You can transcribe voicemail messages up to four hours in length, with file size sizes up to 2GB. Custom caller ID ---------------- Improve connect rates with your outbound calls by setting a custom caller ID number to show up on end users’ phones. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Android Mobile SDK — Getting Started Tutorial | Plivo Plivo Android SDK ================= The Plivo Android SDK lets you create applications capable of making and receiving calls in your Android app. This SDK supports both IPv4 and IPv6 networks, which means you can make and receive calls when your device is connected to a network that uses either or both versions of the protocol. The SDK supports Android versions 5.0 and above and Android API level 21 and above. The current version of the Android SDK is built over the WebRTC framework, which is based on Chromium. It provides high call quality with native WebRTC improvements such as AEC, AGC, and STUN binding requests. Prerequisites ------------- Before you start coding your app: 1. [Register](https://console.plivo.com/accounts/register/) for a Plivo account. You need a Plivo account to create SIP endpoints and Plivo High-Level Objects ([PHLO](https://www.plivo.com/docs/phlo/) ). 2. Create an endpoint to facilitate making and receiving calls from the Android client. For more information about endpoints and their usage, see our [documentation on SIP endpoints](https://www.plivo.com/docs/voice/concepts/sip-endpoint/) . You can automate the creation of endpoints using our REST API; refer to our [Endpoint API Reference Guide](https://www.plivo.com/docs/voice/api/endpoint/) for details. 3. Download and install the latest version of [Android Studio](https://developer.android.com/studio) . 4. Create a [PHLO](https://www.plivo.com/docs/sdk/client/ios/v2/phlo-to-endpoint/) and link it with your endpoint. Getting started with the Plivo Android SDK ------------------------------------------ To create a VoIP-enabled Android app: 1. Download the [Plivo Android SDK AAR file](https://search.maven.org/artifact/com.plivo.endpoint/endpoint/2.0.19/aar) and move it to your app/libs folder.Alternatively, you can include this script into your app/build.gradle file: allprojects { repositories { mavenCentral() } } dependencies { implementation 'com.plivo.endpoint:endpoint:3.0.1-beta.2' }     2. Use our [Plivo Voice Quickstart for Android example app](https://github.com/plivo/plivo-android-quickstart-app) as a starting point to  create your app. Use our [Best Practices Guide](https://www.plivo.com/docs/sdk/client/concepts/mobile/best-practices/) to build the Android app efficiently.    3. Refer to [Android SDK Reference](https://www.plivo.com/docs/sdk/client/android/reference/) documentation for more details on creating  applications capable of making and receiving calls in your app.    4. To set up incoming calls with push notifications, see [Setting Up Push Notification](https://www.plivo.com/docs/sdk/client/android/reference/#setting-up-push-notification) .    5. To manage Android push credentials on the console, see [Managing Push Credentials](https://www.plivo.com/docs/sdk/client/concepts/mobile/manage-push-credentials/) .    6. To debug call-related issues, see our [Mobile SDK Troubleshooting Guide](https://www.plivo.com/docs/sdk/client/troubleshooting-guide/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Voice Callbacks | Plivo Docs 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](https://docs.plivo.com/assets/posts/images/voice/callbacks.png) 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: Congratulations! You've made your first outbound call! 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](/docs/voice/api/call/#make-a-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](/docs/voice/xml/conference/) , [Dial](/docs/voice/xml/dial/) , [GetInput](/docs/voice/xml/getinput/) , and [GetDigits](/docs/voice/xml/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](/docs/voice/xml/request/) 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](/docs/voice/use-cases/receive-incoming-calls/node/) 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](/docs/voice/concepts/callback-configurations/) 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](/docs/voice/concepts/signature-validation/) . Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Account Limits | Voice API Account and feature limits ========================== The Plivo features and components mentioned here have default limits. You can change them through our APIs or XML, or by contacting us. ### Outbound Call API limits By default, all accounts come with a limit of two calls per second. All outbound Call API requests are queued upon acceptance, then dequeued and initiated as per the calls per second (CPS) configured for your Plivo account. ### SIP/browser calls and inbound calls to Plivo numbers Inbound CPS refers to the limitation on outbound calls from SIP and browser clients and inbound calls to Plivo numbers. (These are all called Inbound CPS because outgoing call requests from SIP and browser clients are also inbound requests to Plivo.) The default Inbound CPS limit is 10. Here are three scenarios that show how Inbound CPS limits might apply. In all three, only 10 calls per second will be processed; the rest will be rejected. **Scenario 1** Outbound SIP/browser calls: 11 calls Inbound calls to Plivo numbers: 0 calls **Scenario 2** Outbound SIP/browser calls: 0 calls Inbound calls to Plivo numbers: 11 calls **Scenario 3** Outbound SIP/browser calls: 5 calls Inbound calls to Plivo numbers: 6 calls ### Non-call API limits By default, Plivo limits all accounts to 300 API requests per five seconds. This limit is for all APIs excluding those that initiate a call: * All Call APIs (except “initiate a call”) * All Recording APIs * All Conference APIs * All Endpoint APIs * All Application APIs If you send more non-call requests than the specified limit in the specified duration, Plivo will block the requests and respond with the HTTP error _429 Too Many Requests_. If you see this error, throttle your API requests and retry. **Note:** You can increase your account’s CPS or the rate of non-call API requests, but because doing so incurs extra costs on the part of carriers and server providers, Plivo requires a minimum commitment, the level of which depends on the rate of calls per second or non-call API requests you want. Please [contact our sales team](https://www.plivo.com/contact/sales/) to discuss your situation. Feature-level limits -------------------- In addition to the account-level limits, Plivo has some feature-level limits. ### Time limit for calls The default maximum duration for outbound and inbound calls connected using [Make a Call API](/docs/voice/api/call/#make-a-call) and [Dial XML](/docs/voice/xml/dial/) is four hours starting from the time a call is answered. You can extend the limit to 86,400 seconds (24 hours). ### Call recordings By default, the maximum duration for call recordings is 60 seconds. For calls that you record using [Record API](/docs/voice/api/call/record-calls/) or [Record XML](/docs/voice/xml/record/) , the maximum recording duration is 24 hours. ### Conference calls Two limits have to do with conference calls. * **Participants**: You can have a maximum of 20 participants in a conference room. You can set the maxMembers to be between 1 to 20. * **Duration**: The maximum duration for a conference is 86,400 seconds (24 hours). A conference call will get disconnected after 24 hours. Refer to the [Conference XML element](/docs/voice/xml/conference/) reference page for details. ### Voice transcriptions You can transcribe a call using the [Record API](/docs/voice/api/call/record-calls/#start-recording-a-call) , [Record Conference API](/docs/voice/api/conference/record-conference/#start-recording-a-conference) , [Record XML](/docs/voice/xml/record/) , and [Conference XML](/docs/voice/xml/conference/) . * **Duration**: Our transcription service is limited to calls with a duration greater than 500 milliseconds and less than four hours. * **Recording file size**: The maximum recording file size is 2GB. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Voice STIR/SHAKEN | Plivo Docs STIR/SHAKEN =========== Introduction ------------ Spam and robocalls have become an increasingly significant problem in the US, leading to consumers losing trust in businesses. STIR/SHAKEN is a set of protocols designed for businesses to gain back this trust by authenticating the businesses making calls and the caller ID used in them. STIR/SHAKEN stands for the Secure Telephone Identity Revisited (STIR) and Signature-based Handling of Asserted Information Using toKENs (SHAKEN). Under STIR/SHAKEN, every voice call in the US is assigned an attestation — a stamp of legitimacy provided by the originating service provider, authenticating that the call originated from its network. Calls are then passed to the terminating service provider for verification. There are three levels of call attestations: * Full attestation (A) — The service provider has authenticated its relationship with the customer making the call and the customer is authorized to use the calling number. * Partial attestation (B) — The service provider has authenticated its relationship with the customer making the call, but cannot verify that the customer is authorized to use the calling number. * Gateway attestation (C) — The service provider has authenticated that it has placed the call on its network, but has no relationship with the originator of the call (for example, a call received from an international gateway). Plivo STIR verification ----------------------- For both outbound and inbound Voice API calls, Plivo will display the verification status of a call as a parameter called STIR Verification, which can have one of three values: * **Verified** means the call is from a Verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A. * **Not Verified** means that, for this call, either the caller is not Verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C. * **Not Applicable** means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP). The STIR Verification parameter will be added to: * [Call detail records](https://www.plivo.com/docs/voice/api/call/#retrieve-all-calls) for all inbound and outbound calls. * As part of the information sent to answer\_url, fallback\_url, and hangup\_url webhooks. For outbound calls ------------------ Plivo will sign outbound calls as Verified (attestation A) for calls that use a Plivo DID as caller ID. The DID used should be [rented](https://www.plivo.com/docs/numbers/guides/buy-a-number/) by the same Plivo account that originates the outbound calls. All other outbound calls, assuming they are signed at all, are signed Not Verified (attestation B or C). **Note:** We strongly encourage customers to use Plivo DIDs as caller ID to improve their STIR/SHAKEN verification levels. As the regulatory ecosystem evolves, some of the rules governing the attestation level of an outbound call might be subject to change. For now, Plivo will be signing all outbound calls to the USA unless a customer violates the rules: 1. The calls breach the [Plivo Fair Usage Policy](https://www.plivo.com/legal/tos/) . 2. The calls are identified as unsolicited robocalls. 3. Plivo gets a traceback request from the [Industry Traceback Group](https://www.ustelecom.org/the-industry-traceback-group-itg/) about calls made by the customer. 4. The calls have invalid caller IDs — for instance, if they don’t adhere to E.164 format or have too many digits. In these scenarios, Plivo may stop signing all calls initiated by the customer. That could lead to lower answer rates, because calls won’t be marked as Verified. Worst case, they could be marked as spam by receiving networks. **Note:** For outbound calls to North American toll-free numbers outside the USA, users might see Verified or Not Verified values when in fact these calls are not being signed and the value should be “Not Applicable.” This is because there are shared toll-free numbers, leading to possibility of mismatch. ### Plivo Console logs In the SIP response, Plivo will send in a new header called **X-Plivo-Stir-Verification** whose value is one of the aforementioned three states. You can also see STIR verification values on the Voice > [Logs](https://console.plivo.com/voice/logs/calls/) page of the console as part of CDR. For inbound calls ----------------- Plivo will validate attestation of calls to Plivo DIDs and toll-free numbers in the US. The validated STIR/SHAKEN verification level will be passed as part of webhook requests to various URLs — answer\_url, fallback\_url, and hangup\_url. Verification levels will also be visible on the Plivo [console](https://console.plivo.com/voice/logs/calls/) and in [call detail records](https://www.plivo.com/docs/voice/api/call/#retrieve-a-call) . ### Plivo Console Logs As mentioned earlier, In the SIP response, Plivo will send in a new header called **X-Plivo-Stir-Verification** whose value is one of the aforementioned three states. You can also see STIR verification values on the Voice > [Logs](https://console.plivo.com/voice/logs/calls/) page of the console as part of CDR. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Configurable Callback Retries | Plivo Docs Callback Configurations ======================= Plivo sends HTTP webhooks as callbacks during different states of a call and to many URLs, such as answer\_url, fallback\_url, hangup\_url, action, and callback\_url. To enable users to optimize for lower latency and build fault tolerance into webhook interactions, Plivo offers optional parameters that let developers configure timeouts (the timeframe Plivo has to wait to receive a response from your application server), retry policy, and edge region from which the webhook request is sent to the URL. Regions correspond to [Plivo points of presence](https://support.plivo.com/hc/en-us/articles/360041480231-How-many-connectivity-endpoints-or-points-of-presence-does-Plivo-Zentrunk-SIP-trunking-have-) (PoP). Callback retry scenarios ------------------------ Having the ability to configure callback retries and timeouts improves reliability and event recovery by letting you: * Configure a custom timeout based on your use case. * Set higher timeouts during network problems on your application server. * Set shorter timeouts during an outage on your application server to ensure faster failover to your fallback URL. * Enable retries during client-side service interruptions and delays. Configuration mechanism ----------------------- To set callback configurations for any given URL (answer\_url, fallback\_url, , ring\_url, etc.), you need to append configuration parameters to it in the form of URL extensions (or ”[fragments](https://en.wikipedia.org/wiki/Fragment_identifier) ”) as key-value pairs. * The first key-value pair should start with # * Key and value should be separated by = * Key-value pairs should be separated by & For example: https://example.com/answer_url?query=123#param1=2500¶m2=5500 **Note:** If you don’t append any parameters, the default values from the tables below will apply. Timeouts -------- When Plivo sends an HTTP callback to your webhook URLs during events, 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. When you 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. The timeframe Plivo has to wait to receive a response from your application server is called a timeout. This table shows the allowed and default timeouts available for webhook URLs. | Parameter | Name | Description | Allowed Values | Default | | --- | --- | --- | --- | --- | | ct | Connection timeout | The time in milliseconds (ms) for Plivo to wait while establishing a TCP connection | 100 – 10000 | 2000 | | rt | Read timeout | The time in milliseconds for Plivo to wait:

— to start receiving a response after sending the initial request

— for delay between packets | 100 – 40000 | 40000 | | tt | Total timeout | Upper limit on total time allowed for all timeouts, including retries on a given URL (not including fallback URL) | 100 – 55000 | 55000 | ### Examples 1. https://example.com/answer\_url?query=123#ct=2000 _Connection timeout of two seconds_ 2. https://example.com/answer\_url?query=123#ct=2000&rt=3000 _Connection timeout of two seconds and a read timeout of three seconds_ Retries ------- Plivo lets you configure the number of retries it makes for different webhook URLs and the policy it should use depending on HTTP failure status codes. | Param | Name | Description | Allowed Values | Default | | --- | --- | --- | --- | --- | | rc | Retry count | Number of retry attempts to be made to the same URL if the initial connection fails (not including to fallback URL) | 0 – 5 | 1 | | rp | Retry policy | Type of failure to retry on:

**4xx** → only on 4xx responses

**5xx** → only on 5xx responses

**ct** → TCP/TLS connection failures within the connection timeout

**rt** → no response received within the read timeout

**all** → all the above | Comma-separated list of values — for example, rp=ct,rt | ct,rt | **Note:** If a partial response is received from your app server, Plivo will not make a retry attempt. ### Examples 1. https://example.com/answer\_url?query=123#rt=3000&rp=ct,rt _Retry on both connect and read timeout, and reduce the read timeout to three seconds._ 2. https://example.com/answer\_url?query=123#rc=3&ct=2000 _Retry on connection failure, but with a two-second connection timeout. If there is no connection in two seconds, retry three times, for a total of four attempts to connect._ Edge Region ----------- An edge region is the geographical region from which Plivo initiates an HTTP webhook to the answer\_url, fallback\_url, hangup\_url, action, or callback\_url URLs. Plivo maintains edge clusters in four regions: * North California (United states) * North Virginia (United States) * Frankfurt (Germany) * Singapore To ensure minimum latency, Plivo automatically chooses the nearest region for all callbacks we initiate, but developers can configure the region for each URL using the `er` parameter: | Param | Name | Description | Allowed Values | Default | | --- | --- | --- | --- | --- | | er | Edge Region | Specifies the edge region where webhooks get initiated from. This parameter needs to be either a selection strategy or a specific region.
Region Selection Strategies:
**nearest** → selects the region geographically closest to the location of the URL.
**local** → selects the same region as the media server where the call media is hosted.
Specific region:
n\_california, n\_virginia, frankfurt, singapore | * nearest
* local
* n\_california
* n\_virginia
* frankfurt
* singapore | nearest | ### Examples 1. https://example.com/answer\_url?query=123#er=n\_california _The HTTP webhook to this URL from Plivo will be initiated from Plivo’s North California edge region._ 2. https://example.com/answer\_url?query=123#er=nearest _The HTTP webhook to this URL from Plivo will be initiated from the Plivo’s edge region that is nearest to the location of the URL._ Applicable URLs --------------- Callback retries apply to this list of URLs associated with Plivo’s [Voice applications on the console](https://console.plivo.com/voice/applications/) , API requests, and XML elements: ### Voice applications on console * Primary Answer URL * Fallback Answer URL * Hangup URL ### API [Make a call](/docs/voice/api/call/#make-a-call) : * answer\_url * ring\_url * hangup\_url * fallback\_url * machine\_detection\_url [Transfer a call](/docs/voice/api/call/#transfer-a-call) : * aleg\_url * bleg\_url [Record a call](/docs/voice/api/call/record-calls/) : * transcription\_url * callback\_url [Record a conference](/docs/voice/api/conference/record-conference/) : * transcription\_url * callback\_url ### XML [Dial](/docs/voice/xml/dial/) : * action * confirmSound * dialMusic * callbackUrl [Conference](/docs/voice/xml/conference/) : * action * callbackUrl * waitSound [GetInput](/docs/voice/xml/getinput/) : * action * interimSpeechResultsCallback [GetDigits](/docs/voice/xml/getdigits/) : * action [Record](/docs/voice/xml/record/) : * action * transcriptionUrl * callbackUrl [Redirect](/docs/voice/xml/redirect/) Inapplicable URLs ----------------- Callback retry parameters don’t apply to any of these audio URLs: ### API [Play audio on a call](/docs/voice/api/call/play-audio-on-calls/#play-audio-on-a-call) [Play audio to a conference member](/docs/voice/api/conference/member/#play-audio-to-a-member) ### XML [PreAnswer XML](/docs/voice/xml/preanswer/) [Play XML](/docs/voice/xml/play/#play-music) These URLs use our standard configuration values: * Connection timeout: 2 seconds * Read timeout: 120 seconds * Retry count: 1 * Retry policy: all Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Outbound Voice Geo Permissions | Plivo Docs Outbound voice geo permissions ============================== Plivo can protect your account from fraud by restricting the set of countries your account can call. If, for example, you intend to place calls to numbers in North America only, you can disable call routes to all other continents and thereby reduce the risk of fraud. Similarly, if you’re running an inbound call center, or your use case doesn’t involve outbound calling to PSTN numbers, you can block outbound routes to all countries as a precautionary measure. To manage geo permissions, navigate to Voice > [Geo Permissions](https://console.plivo.com/voice/settings/geo-permissions/) on the Plivo console. ![voice prevention- Geo_preferences](/assets/posts/images/voice/geopermissions/countrypermissions.png) Here you’ll see a list of all countries. You can filter the list by selecting specific geographic regions or countries. Geo permission configurations are applied immediately to all calls initiated via Plivo APIs and Dial XML. API calls to blocked countries are rejected with HTTP response code 403 and the error message “Calls to this destination country are barred.” Calls initiated with Dial XML are dropped automatically. The hangup cause in the Call Detail Report for such calls is set to “Destination Country Barred” (Code 2030). See our list of [hangup causes](/docs/voice/troubleshooting/hangup-causes/) . Calling premium numbers ----------------------- Premium rate numbers cost callers more than normal numbers. Part of that charge is paid to the service provider, which puts premium rate numbers at high risk of being exploited via traffic pumping, a type of telecom fraud in which bad actors artificially inflate traffic to their premium rate numbers. When done across countries, this type of toll fraud is known as International Revenue Share Fraud (ISRF). Most businesses never need to call premium rate numbers, so by default Plivo blocks calls to all phone numbers with high-risk prefixes as a way to prevent unwanted charges. Plivo has identified thousands of premium rate and high-risk prefixes. You can export a list of these prefixes from the Voice > Geo Permissions > [High-Risk Permissions](https://console.plivo.com/voice/settings/geo-permissions/) screen of the Plivo console. Plivo regularly updates this list based on factors such as the rates associated with the premium numbers, call patterns, and third-party trends. ![voice prevention-calling_premium_numbers](https://docs.plivo.com/assets/posts/images/voice/geopermissions/highriskpermissions.png) If you have a legitimate need to make calls to premium rate or high-risk numbers, you can request activation of high-risk permissions for your account or a particular subaccount by contacting our support team and providing them with details of your use case. Plivo rejects API calls to blocked prefixes with an HTTP response code 403 and the error message “Calls to this destination number are barred.” Calls to blocked prefixes initiated with the Dial XML element are automatically dropped. The Call Detail Record for such calls indicates the hangup cause as “Destination Number Barred (Code 2040).” Overriding preferences for specific subaccounts ----------------------------------------------- Default preferences apply to all calls initiated from the main account and all subaccounts, but you can override geo permissions at the subaccount level. To specify preferences for a subaccount, select the subaccount from the Account drop-down, enter your preferences, and click Save Changes. ![voice prevention-config_specific_subaccounts](/assets/posts/images/voice/geopermissions/subaccount.png) For more information, see our an [article in our support portal](https://support.plivo.com/hc/en-us/sections/360008303651-Voice-Geo-Permissions) . Geo permissions disabled by Plivo --------------------------------- Plivo analyzes call trends and disables geo permissions when we discover suspicious activity toward any country. You might see a “Disabled by Plivo” tag for a country or a message saying “Please contact Plivo support to re-enable geo permissions for any country that’s disabled below.” This indicates that Plivo has identified suspicious activity and disabled the geo permissions to avoid calls getting placed from your account to unknown numbers and destinations. To unblock geo permissions in such instances, [contact Plivo support](https://support.plivo.com/hc/en-us/requests/new?ticket_form_id=360000156292) . ![disabled by Plivo](/assets/posts/images/voice/geopermissions/disabledbyplivo.png) These response codes will show in your call detail report if geo permissions are disabled: _SIP Response Code: 403 - Barred Country; Zentrunk Hangup Code: 4650_ _Description: The number has been blocked in geo permissions settings. Any calls made to this number belong to a specific country or number group will not go through since it has been barred._ Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # Plivo SIP Endpoints - Getting Started Tutorial | Plivo Plivo SIP endpoints =================== Plivo endpoints expand the capabilities of your existing SIP phones, allowing you to add custom business logic when you make or receive calls. Traditionally, SIP phones had very basic functionality and needed to be connected to a PBX to bring them to life. With Plivo endpoints, you no longer need to set up and manage your phone system. Any Plivo application can implement the business logic needed to control your SIP phone, using any of your favorite coding languages without any need to understand the telecommunications details. Plivo supports all common SIP-based softphones and hardware phones. With Plivo and your SIP phones, you can implement: * **Instant conferencing** — You can add calls made via a SIP phone registered with Plivo directly to a conference bridge. * **Access control** — With a few lines of code, you can add the ability to restrict calls made from SIP phones or limit a phone to only accept calls. * **Monitoring and reporting** — You can monitor all calls made or received on a SIP phone, and create custom dashboards and reports to analyze the data you get from the APIs. * **Smart routing** — You can add intelligent extensions and shortcuts to route calls to and from traditional phone networks and WebRTC-enabled devices. How it works ------------ Once you configure and set up your SIP phone, register it with Plivo. When you initiate a call using the SIP phone, you don’t connect directly to another phone or extension. Instead, you instruct Plivo to fetch XML from the attached application on your server to handle the call request. This is similar to the way that Plivo handles incoming calls from a regular phone number. You can use all Plivo XML elements to handle a call request. You can also use the Dial element to dial out to a regular phone, WebRTC device, or another SIP phone. Getting started --------------- 1. Sign up for a [Plivo account](https://console.plivo.com/accounts/register/) . 2. Create an endpoint by visiting Voice > [Endpoints](https://console.plivo.com/endpoint/) , clicking on Add New Endpoint, and filling in the required details. The Username should be a unique ID for the endpoint. 3. Plivo adds random numbers after the username you enter. If, for instance, you choose “obiwan” as your username, Plivo might set it up as “obiwan01356015703850523884.” Specify a password you can use to authenticate the endpoint. Set an alias (maybe “ben” in this case) which Plivo uses when it displays all your endpoints, and optionally a subaccount to associate the endpoint with. Using a default dialer application ---------------------------------- To start making calls, attach Plivo’s default direct dial application to the endpoint you created. * If you already created the endpoint, go to the Endpoints page and click on the endpoint username. This will open an endpoint edit window. Select Direct Dial from the Application drop-down list. ![SIP Endpoint](https://docs.plivo.com/assets/posts/images/voice/sipendpoints/Directdial.jpg) * If you’re creating a new endpoint, select Direct Dial from the Application drop-down list. Customizing the endpoint application ------------------------------------ When you make a call from a softphone, Plivo sends a request to the answer URL of the application attached to the endpoint with call-related parameters. To process the call, Plivo requires a valid XML response from the answer URL. Let’s say, in our case, that we want to create a quick dial application and make an outbound call to the number entered from the softphone. The answer URL will receive a request with the From and To parameters. Our application needs to parse these parameters and return a Dial XML element with the correct attributes. 18003231234 When this XML is returned to the request, Plivo will make an outbound call to 18003231234 and connect it to the softphone. For technical information, see our [Endpoint API reference documentation](/docs/voice/api/endpoint/) . Configure your SIP phone ------------------------ Once you have an endpoint set up you can associate a SIP phone with it. The way to do that varies depending on the phone. Here‘s how the process works with a Bria Solo softphone. * Create an account using the [Bria portal](https://www.counterpath.com/bria-solo/) . * To configure a voice account, use the details of the Plivo SIP endpoint you created. ![X-lite preference](https://docs.plivo.com/assets/posts/images/voice/sipendpoints/account_creation.png) * Download and install the softphone software. If you’re on Mac or Windows, download [Bria Solo](https://www.counterpath.com/bria-solo/) (formerly X-Lite). On Linux, download [Blink](https://icanblink.com/) . For this tutorial, we use Bria Solo. * Open the application and enable auto import voice account details to import the SIP account details and credentials. **Note:** Field names may vary based on make and model of the SIP phone, but the configuration will still work. ![X-lite account](https://docs.plivo.com/assets/posts/images/voice/sipendpoints/sipaccountdetails.png) * Click on OK when you’re done. * Your endpoint entry in the list should show as Enabled, indicating that your SIP phone successfully registered with Plivo. Examples -------- We have examples of a direct dial application written in multiple languages on [GitHub](https://github.com/plivo/directdial) that you can customize based on your needs. Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates Thank you for your feedback! --- # IP Address Whitelisting | Plivo Developers IP address whitelisting ======================= To ensure that your communication infrastructure doesn’t block communication with Plivo, we encourage you to whitelist these IP address ranges and ports on your firewall for SIP signaling and RTP media traffic. [Subscribe](/docs/voice/concepts/ip-address-whitelisting/#subscription-section) to be notified of any updates regarding IP address changes via email or RSS feed. SIP signaling ------------- | | | | | --- | --- | --- | | **Type** | **IP Addresses** | **Ports** | | SIP phones (phone.plivo.com & app.plivo.com) | 52.9.254.123/32
52.9.254.127/32
216.120.187.64/32
216.120.187.65/32
216.120.187.66/32
216.120.187.67/32
216.120.187.68/32
204.89.148.64/32
204.89.148.65/32
204.89.148.66/32
204.89.148.67/32
204.89.148.68/32 | 5060, 5080 (UDP)
5060, 5061, 5063, 5080, 443 (TCP) | | Mobile phones (mobile.phone.plivo.com) | 2600:1f1c:4ad:2f02:ac95:55cc:9a28:3891/128 | 5060, 5080 (UDP)
5060, 5061, 5063, 5080, 443 (TCP) | | External SIP endpoints | 13.52.9.4/32
13.52.9.5/32
18.214.109.132/32
18.214.109.133/32 | 5060 (UDP) | RTP media servers ----------------- | | | | | --- | --- | --- | | **Regions** | **IP Addresses** | **Ports** | | San Jose, California, USA | 216.120.187.64/25
216.120.187.192/27 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | Ashburn, Virginia, USA | 204.89.148.64/25
204.89.148.192/27 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | Frankfurt, Germany | 3.120.121.128/26 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | São Paulo, Brazil | 54.233.191.0/27
18.228.70.64/26 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | Sydney, Australia | 13.238.202.192/26 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | Singapore | 52.220.63.176/28
204.89.149.64/27
204.89.149.128/27 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | | Mumbai, India | 204.89.151.64/26
204.89.151.128/25 | 16384 - 32768 (UDP)
10000 - 30000 (UDP/TCP) | API --- Since we don’t support static IP address ranges for the API, you don’t need to whitelist IP addresses for Voice API communication.  The domain to whitelist for Plivo APIs is api.plivo.com. Browser SDK client and Call Insights ------------------------------------ We don’t support static IP ranges for the Browser SDK client, Browser SDK fallback client, or Call Insights. You can whitelist their domains. * client.plivo.com * client-fb.plivo.com * insights.plivo.com STUN servers for Browser SDK ---------------------------- The Plivo Browser SDK utilizes the listed STUN servers to initiate WebRTC media communications. The STUN server aids in identifying a device’s public IP address and port number for communication. * stun:stun.plivo.com:3478 * stun:stun-fb.plivo.com:3478 * stun:stun.l.google.com:19302 Protocol Whitelisting --------------------- When using the browser and mobile SDK for calls, please ensure the protocols - SIP, RTP, STUN, and DTLS are allowed by your firewall and ISP. Callbacks from Plivo -------------------- Some Plivo APIs and XML elements support callback events. To make sure those callbacks are not blocked, allow traffic from these Plivo IP addresses to your web applications (ports defined by you; for HTTPS, default is 443, for HTTP it’s 80). These IP addresses are NAT gateway IPs associated with our HTTP(s) OutProxy instance. | | | | --- | --- | | **Regions** | **IP Addresses** | | San Jose, California, USA | 13.56.175.187/32
13.57.139.231/32 | | Ashburn, Virginia, USA | 18.211.55.148/32
18.211.27.222/32
204.89.148.70/32 | | Frankfurt, Germany | 3.120.80.110/32
35.157.59.132/32 | | São Paulo, Brazil | 18.228.96.85/32
18.228.143.199/32 | | Sydney, Australia | 13.238.88.135/32
52.62.46.143/32 | | Singapore | 52.220.250.27/32
18.136.128.252/32 | | Mumbai, India | 3.7.4.233/32
3.7.220.174/32 | ![Your Email](https://docs.plivo.com/assets/dist/images/v2/icon/ic-email.svg)Subscribe to updates SUBSCRIBE Rate this page 🥳 Thank you! It means a lot to us! Help Us Improve Thank you so much for rating the page, we would like to get your input for further improvements! SUBMIT Subscribe to Updates ![support ticket](https://docs.plivo.com/assets/dist/images/v2/contact/ic_thank you.svg) Thank you! We have updated your subscription preferences! First Name First name is required Last Name Last name is required Work Email Work email is required SUBSCRIBE * * * [![](https://docs.plivo.com/assets/dist/images/rss-logo.svg)Get RSS Feed](/voice_ips_whitelisting.rss) By submitting this form, you agree we may contact you in the manner described in our [Privacy Policy](/legal/privacy/ "Privacy Policy") . By submitting this form, you agree we may contact you in the manner described in our [Privacy Policy](/legal/privacy/ "Privacy Policy") . Thank you for your feedback! ---