Metadata-Version: 2.4
Name: langchain-plivo-tools
Version: 0.1.0
Summary: An integration package connecting Plivo and LangChain
Project-URL: Homepage, https://github.com/plivo-dev/langchain-plivo-tools
Project-URL: Repository, https://github.com/plivo-dev/langchain-plivo-tools
Project-URL: Documentation, https://github.com/plivo-dev/langchain-plivo-tools
Project-URL: Bug Tracker, https://github.com/plivo-dev/langchain-plivo-tools/issues
Project-URL: Release Notes, https://github.com/plivo-dev/langchain-plivo-tools/releases
Author-email: Plivo <oss@plivo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: calls,langchain,messaging,plivo,sms,telephony,voice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.10
Requires-Dist: langchain-core<2,>=0.3
Requires-Dist: plivo<5,>=4.60
Description-Content-Type: text/markdown

# langchain-plivo-tools

[![PyPI version](https://img.shields.io/pypi/v/langchain-plivo-tools.svg)](https://pypi.org/project/langchain-plivo-tools/)
[![Python versions](https://img.shields.io/pypi/pyversions/langchain-plivo-tools.svg)](https://pypi.org/project/langchain-plivo-tools/)
[![License MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI](https://github.com/plivo-dev/langchain-plivo-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/plivo-dev/langchain-plivo-tools/actions/workflows/ci.yml)

This package connects [Plivo](https://www.plivo.com) to [LangChain](https://python.langchain.com), so agents can send SMS messages and place voice calls through Plivo as tools.

## Installation

```bash
pip install langchain-plivo-tools
```

## Setup

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

```bash
export PLIVO_AUTH_ID="your-auth-id"
export PLIVO_AUTH_TOKEN="your-auth-token"
export PLIVO_FROM_NUMBER="+14155551234"
```

You can find the Auth ID and Auth Token on the [Plivo console](https://cx.plivo.com/?utm_source=github&utm_medium=oss&utm_campaign=langchain-plivo-tools) 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

```python
from langchain_plivo_tools import PlivoSendMessageTool

tool = PlivoSendMessageTool()

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

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

```python
tool = PlivoSendMessageTool(
    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

`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.

```python
from langchain_plivo_tools import PlivoMakeCallTool

tool = PlivoMakeCallTool()

tool.invoke({"to": "+14155551234", "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.

```xml
<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.

```xml
<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.

```bash
export PLIVO_ANSWER_METHOD="POST"
```

```python
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.

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

## Development

```bash
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`.

```bash
make integration_test
```

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
