Plivo Getting Started: Account Setup & First API Call (2026)

Getting started overview

Integrating Plivo into an application involves a series of steps designed to enable programmatic control over communication channels like SMS and voice. The process begins with account creation, followed by the retrieval of API credentials necessary for authenticating requests. Users then acquire a Plivo phone number, which acts as the sender for outbound communications. Finally, developers can make their first API call, often using one of Plivo's official SDKs or a direct HTTP request.

This guide outlines the essential steps to get a Plivo account operational and execute a basic communication task. Subsequent development often involves configuring webhooks for incoming messages or calls, managing phone numbers, and scaling communication features. For a comprehensive overview of Plivo's capabilities, refer to the Plivo documentation portal.

Quick Reference Table

Create an account and get keys

Before making any API calls, a Plivo account is required. Plivo offers a free trial that includes test credits for initial development and testing without immediate charges. The registration process typically involves providing an email address, setting a password, and verifying contact information. Upon successful registration, users gain access to the Plivo Console.

Signing Up for Plivo

1. Navigate to the Plivo signup page.
2. Enter the required personal and company details.
3. Verify your email address and phone number as prompted.
4. Complete any additional onboarding steps to access the Plivo Console.

Retrieving API Credentials

API requests to Plivo are authenticated using HTTP Basic Authentication, requiring an Auth ID and an Auth Token. These credentials uniquely identify your account and authorize API interactions. They are found on the main dashboard of your Plivo Console.

1. Log in to the Plivo Console.
2. On the dashboard, locate the section displaying your Auth ID and Auth Token. The Auth Token is usually hidden for security and can be revealed by clicking a "show" button.
3. Securely store these credentials. They should not be hardcoded directly into public repositories or client-side code (OAuth 2.0 security considerations).

Acquiring a Plivo Phone Number

To send SMS messages or make voice calls, you need a Plivo phone number. These numbers are purchased through the console and can be configured for specific use cases (e.g., SMS-enabled, voice-enabled, local, toll-free).

1. From the Plivo Console, navigate to Phone Numbers > Buy New Number.
2. Select your desired country, number type (e.g., local, toll-free), and capabilities (SMS, Voice).
3. Search for available numbers and click to purchase one. This will deduct from your trial credits or account balance.

Your first request

After obtaining your credentials and a phone number, you can make your first API request. This example demonstrates sending an SMS using the Python SDK, a common starting point. Plivo provides SDKs for various languages, simplifying interaction with their APIs.

Setting up the Python SDK

First, install the Plivo Python SDK:

pip install plivo

Sending an SMS Message

Replace YOUR_AUTH_ID, YOUR_AUTH_TOKEN, YOUR_PLIVO_NUMBER, and DESTINATION_NUMBER with your actual credentials and numbers.

import plivo

# Your Plivo Auth ID and Auth Token
AUTH_ID = 'YOUR_AUTH_ID'
AUTH_TOKEN = 'YOUR_AUTH_TOKEN'

# Initialize the Plivo client
client = plivo.RestClient(AUTH_ID, AUTH_TOKEN)

try:
    # Send an SMS message
    response = client.messages.create(
        src='YOUR_PLIVO_NUMBER',  # Your Plivo phone number
        dst='DESTINATION_NUMBER', # The recipient's phone number
        text='Hello from Plivo!',
    )

    print(response)

except Exception as e:
    print(f"An error occurred: {e}")

Executing this script will send an SMS message from your Plivo number to the specified destination. The response object will contain details about the message, including its UUID (Unique Universal Identifier).

Making a Voice Call (Optional)

For making a voice call, the process is similar, but requires specifying a Plivo Markup Language (PML) URL or direct PML instructions. PML defines the actions Plivo should take during a call.

import plivo

AUTH_ID = 'YOUR_AUTH_ID'
AUTH_TOKEN = 'YOUR_AUTH_TOKEN'

client = plivo.RestClient(AUTH_ID, AUTH_TOKEN)

try:
    response = client.calls.create(
        from_='YOUR_PLIVO_NUMBER',  # Your Plivo phone number
        to_='DESTINATION_NUMBER',    # The recipient's phone number
        answer_url='http://example.com/answer_pml_url', # URL to your PML instructions
        answer_method='GET'
    )
    print(response)

except Exception as e:
    print(f"An error occurred: {e}")

The answer_url must point to a publicly accessible URL that returns valid PML, instructing Plivo on what to do when the call is answered (e.g., play text-to-speech, connect to another party). More details on Plivo's voice API are available in their documentation.

Common next steps

Once you've successfully made your first API call, several common next steps enhance your Plivo integration:

• Configure Webhooks: Set up webhooks in your Plivo Console to receive notifications for incoming SMS messages, incoming calls, or status updates on sent messages and calls. This is crucial for building interactive applications. For example, to handle incoming SMS, you would set an SMS Inbound URL for your Plivo number.
• Explore SDKs: Familiarize yourself with other methods and features available in your chosen SDK, such as managing messages, calls, or phone numbers programmatically.
• Implement Error Handling: Add robust error handling to your code to gracefully manage API failures, network issues, or invalid inputs.
• Monitor Usage and Billing: Regularly check your Plivo Console for usage reports and billing details to manage costs effectively, especially when transitioning from trial to paid usage.
• Security Best Practices: Review Plivo's API security recommendations, including protecting your Auth ID and Auth Token, validating webhook signatures, and using HTTPS for all communication. Securing API keys is a fundamental principle of API integration, as highlighted in Google's API key best practices.
• Upgrade Account: If you're on a trial, consider upgrading your account to access full features and remove trial limitations. This typically involves adding billing information.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check Credentials: Double-check that your Auth ID and Auth Token are correctly entered. Even a single character mismatch will result in an authentication failure.
• Verify Phone Numbers: Ensure that both the source (Plivo) number and the destination number are correctly formatted, including the country code (e.g., +1XXXXXXXXXX for North America). Confirm your Plivo number has the necessary capabilities (SMS or Voice) enabled.
• Account Balance/Trial Credits: Confirm you have sufficient trial credits or account balance. Outbound communications consume credits, and insufficient funds will prevent messages or calls from being processed.
• Network Connectivity: Ensure your application has outbound internet access to reach Plivo's API endpoints.
• Firewall Settings: If you are within a corporate network, check if firewall rules are blocking outbound HTTP/HTTPS requests to Plivo's API endpoints.
• API Error Responses: Pay close attention to the error messages returned by the API. Plivo's API error codes documentation provides details on common issues and their resolutions.
• SDK Version: Ensure you are using a current and compatible version of the Plivo SDK. Outdated SDKs might have compatibility issues or missing features.
• Plivo Debugger: Utilize the Plivo Console's Debug Center to inspect logs and error details for specific messages or calls, which can provide granular insights into why a request failed.
• Public URL for Callbacks: For voice calls or receiving SMS, ensure any URLs provided for webhooks (e.g., answer_url, message_url) are publicly accessible and correctly configured to accept Plivo's requests.
• Contact Support: If issues persist, Plivo's support team can provide assistance. Always be prepared to share relevant request IDs or error messages for quicker resolution.