langchain-plivo-tools 0.1.0

An integration package connecting Plivo and LangChain

langchain-plivo-tools

This package connects Plivo to LangChain, so agents can send SMS messages and place voice calls through Plivo as tools.

Installation

pip install langchain-plivo-tools

Setup

Set your Plivo credentials as environment variables, or pass them to the tool directly.

export PLIVO_AUTH_ID="your-auth-id"
export PLIVO_AUTH_TOKEN="your-auth-token"
export PLIVO_FROM_NUMBER="[phone]"

You can find the Auth ID and Auth Token on the Plivo console dashboard. The from number must be a Plivo phone number in E.164 format that is enabled for the service you are using, either SMS or voice.

Send an SMS

from langchain_plivo_tools import PlivoSendMessageTool

tool = PlivoSendMessageTool()

tool.invoke({"body": "Your order has shipped.", "to": "[phone]"})

Credentials can also be passed in code instead of the environment.

tool = PlivoSendMessageTool(
    auth_id="your-auth-id",
    auth_token="your-auth-token",
    from_number="[phone]",
)

The tool returns the Plivo message UUID on success. Numbers use E.164 format.

Make a call

PlivoMakeCallTool places a phone call. Plivo answers the call by fetching an Answer URL that returns Plivo XML, so you must host an endpoint that returns that XML and set PLIVO_ANSWER_URL in addition to the credentials above, or pass answer_url to the tool.

from langchain_plivo_tools import PlivoMakeCallTool

tool = PlivoMakeCallTool()

tool.invoke({"to": "[phone]", "message": "Your monitor is down."})

The Answer URL contract

When the call connects, Plivo fetches your Answer URL and expects a Plivo XML document in response. By default the URL is fetched with GET, because the optional message you pass is appended to the Answer URL as a message query parameter. Your endpoint reads that parameter and returns XML that speaks it. A minimal response looks like this.

<Response><Speak>{message}</Speak></Response>

For example, when you invoke the tool with message="Your monitor is down.", Plivo requests your Answer URL with ?message=Your+monitor+is+down. and your endpoint should return this.

<Response><Speak>Your monitor is down.</Speak></Response>

To have your endpoint receive the parameters as a POST body instead, set the answer method to POST, either through the environment or on the tool.

export PLIVO_ANSWER_METHOD="POST"

tool = PlivoMakeCallTool(answer_method="POST")

The tool returns the Plivo request UUID on success.

Configuration

Every setting reads from an environment variable, and any of them can be overridden by passing the matching argument to the tool constructor.

Environment variable	Constructor argument	Used by	Purpose
PLIVO_AUTH_ID	auth_id	both tools	Plivo account Auth ID
PLIVO_AUTH_TOKEN	auth_token	both tools	Plivo account Auth Token
PLIVO_FROM_NUMBER	from_number	both tools	Plivo number that sends the SMS or places the call
PLIVO_ANSWER_URL	answer_url	PlivoMakeCallTool	Endpoint that returns Plivo XML when the call connects
PLIVO_ANSWER_METHOD	answer_method	PlivoMakeCallTool	HTTP method Plivo uses to fetch the Answer URL, defaults to GET

Using the tools with a LangChain agent

Both tools are standard LangChain tools, so you can bind them to a chat model or hand them to an agent.

from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent

from langchain_plivo_tools import PlivoMakeCallTool, PlivoSendMessageTool

tools = [PlivoSendMessageTool(), PlivoMakeCallTool()]

model = init_chat_model("claude-sonnet-4-5-20250929", model_provider="anthropic")
agent = create_react_agent(model, tools)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Text [phone] to let them know their order shipped.",
            }
        ]
    }
)
print(result["messages"][-1].content)

Development

make install
make test
make lint

Integration tests place a real API call and run only when PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, PLIVO_FROM_NUMBER and PLIVO_TO_NUMBER are set. Calls also need PLIVO_ANSWER_URL.

make integration_test

License

This project is licensed under the MIT License. See LICENSE for details.