langchain-plivo-tools

Plivo SMS and voice tools for LangChain agents. An agent sends text messages and places phone calls through Plivo.

Requirements

Installation

pip install langchain-plivo-tools

Upgrading from 0.1.0

The two tool classes lost their Tool suffix in 0.2.0 to match the naming used across LangChain tool packages.

The old names still import and resolve to the renamed classes, raising a DeprecationWarning. They are scheduled for removal in 0.3.0. The tool names the model sees, plivo_send_message and plivo_make_call, are unchanged, so agent behaviour does not shift on upgrade.

Setup

Set the 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="+14155551234"

The Auth ID and Auth Token are on the Plivo console dashboard. The from number must be a Plivo phone number in E.164 format, enabled for SMS, voice, or both.

Send an SMS

from langchain_plivo_tools import PlivoSendMessage

tool = PlivoSendMessage()

tool.invoke({"body": "Your order has shipped.", "to": "+14155551234"})

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

tool = PlivoSendMessage(
    auth_id="your-auth-id",
    auth_token="your-auth-token",
    from_number="+14155551234",
)

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

Make a call

PlivoMakeCall places a phone call. Plivo answers the call by fetching an Answer URL that returns Plivo XML, so that endpoint has to be hosted separately. Its address goes in PLIVO_ANSWER_URL, alongside the credentials above, or is passed as answer_url to the tool.

from langchain_plivo_tools import PlivoMakeCall

tool = PlivoMakeCall()

tool.invoke({"to": "+14155551234", "message": "Your monitor is down."})

The Answer URL contract

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

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

Invoking the tool with message="Your monitor is down." makes Plivo request the Answer URL with ?message=Your+monitor+is+down., and the endpoint returns this.

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

To 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 = PlivoMakeCall(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.

Using the tools with a LangChain agent

Both tools are standard LangChain tools, so they can be bound to a chat model or handed to an agent.

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

from langchain_plivo_tools import PlivoMakeCall, PlivoSendMessage

tools = [PlivoSendMessage(), PlivoMakeCall()]

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 +14155551234 to let them know their order shipped.",
            }
        ]
    }
)
print(result["messages"][-1].content)

Every tool at once with the toolkit

PlivoToolkit hands an agent all of the Plivo tools in one call, which keeps the agent setup unchanged as more tools are added to the package.

from langchain_plivo_tools import PlivoToolkit

agent = create_react_agent(model, PlivoToolkit().get_tools())

The toolkit reads the same environment variables as the individual tools, and any argument passed to it is forwarded to every tool that accepts one.

toolkit = PlivoToolkit(
    auth_id="your-auth-id",
    auth_token="your-auth-token",
    from_number="+14155551234",
    answer_url="https://example.com/answer",
)

A tool whose configuration is incomplete is left out of the returned list rather than raising, because an account that only sends SMS has no reason to set an Answer URL. Each omission raises a warning naming the missing setting, so a tool absent from an agent stays traceable. Nothing being configurable is an error.

# With credentials set but no PLIVO_ANSWER_URL:
PlivoToolkit().get_tools()
# UserWarning: Some Plivo tools are missing from the toolkit.
# PlivoMakeCall (Missing Plivo settings: PLIVO_ANSWER_URL. ...)
# -> [PlivoSendMessage()]

Security

• The Auth Token is held as a SecretStr, keeping it out of repr() and log output
• Credentials are read from the environment or passed to the constructor, and this package writes neither to disk
• Both tools perform billable actions against a number the model supplies. No destination allowlist or rate limit is applied here, so those controls belong in the host application or in Plivo spend limits
• The message argument reaches the Answer URL as a query parameter. An endpoint placing it into XML has to escape it first, because unescaped input can alter the XML document

Limitations

• SMS only. MMS and WhatsApp are not covered
• Number lookup and Verify are not included
• PlivoMakeCall needs a separately hosted Answer URL, because Plivo does not speak text handed straight to the call API

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.