> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plivo

> PlivoTools enables agents to interact with Plivo for sending SMS, placing calls, and looking up phone numbers.

**PlivoTools** enables an Agent to interact with [Plivo](https://www.plivo.com/docs/) services, such as sending SMS, placing calls, looking up numbers, and reviewing call and message history.

## Prerequisites

The following examples require the `plivo` library and a Plivo Auth ID and Auth Token, which can be obtained from the [Plivo console](https://cx.plivo.com).

```shell theme={null}
uv pip install plivo openai
```

Set the following environment variables:

```shell theme={null}
export PLIVO_AUTH_ID=***
export PLIVO_AUTH_TOKEN=***
```

## Example

The following agent will look up carrier information for a phone number using Plivo:

```python theme={null}
from agno.agent import Agent
from agno.tools.plivo import PlivoTools

agent = Agent(
    instructions=[
        "Use your tools to send messages and place calls using Plivo.",
    ],
    tools=[PlivoTools()],
)

agent.print_response("Look up carrier info for +1234567890", markdown=True)
```

## Toolkit Params

| Name                      | Type            | Default | Description                                                                                         |
| ------------------------- | --------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `auth_id`                 | `Optional[str]` | `None`  | Plivo Auth ID for authentication. If not provided, uses `PLIVO_AUTH_ID` environment variable.       |
| `auth_token`              | `Optional[str]` | `None`  | Plivo Auth Token for authentication. If not provided, uses `PLIVO_AUTH_TOKEN` environment variable. |
| `debug`                   | `bool`          | `False` | Enable debug logging for troubleshooting.                                                           |
| `enable_send_sms`         | `bool`          | `True`  | Enable the send\_sms functionality.                                                                 |
| `enable_make_call`        | `bool`          | `True`  | Enable the make\_call functionality.                                                                |
| `enable_get_call_details` | `bool`          | `True`  | Enable the get\_call\_details functionality.                                                        |
| `enable_list_messages`    | `bool`          | `True`  | Enable the list\_messages functionality.                                                            |
| `enable_list_calls`       | `bool`          | `True`  | Enable the list\_calls functionality.                                                               |
| `enable_lookup_number`    | `bool`          | `True`  | Enable the lookup\_number functionality.                                                            |
| `all`                     | `bool`          | `False` | Enable all functionality.                                                                           |

## Toolkit Functions

| Function           | Description                                                                                                                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send_sms`         | Sends an SMS to a single recipient. Parameters: `to` (str, E.164 format), `from_` (str, a Plivo number, short code, or alphanumeric sender ID), `body` (str). Returns the message UUID if successful or an error message if failed.                                                       |
| `make_call`        | Places an outbound call. Parameters: `to` (str, E.164 format), `from_` (str, a Plivo voice-enabled number), `answer_url` (str, must return Plivo XML), `answer_method` (str, `GET` or `POST`, default `POST`). Returns the call request UUID if successful or an error message if failed. |
| `get_call_details` | Retrieves details of a call using its UUID. Parameters: `call_uuid` (str). Returns a dictionary with the call's `to`, `from`, `state`, `duration`, `direction`, `initiation_time`, `answer_time`, and `total_amount`.                                                                     |
| `list_messages`    | Lists recent messages. Parameters: `limit` (int, default 20, capped at the Plivo per-request maximum of 20), `offset` (int, default 0, for paging past the cap), `message_direction` (str, optional, `inbound` or `outbound`). Returns a list of message details.                         |
| `list_calls`       | Lists recent calls. Parameters: `limit` (int, default 20, capped at the Plivo per-request maximum of 20), `offset` (int, default 0, for paging past the cap), `call_direction` (str, optional, `inbound` or `outbound`). Returns a list of call details.                                  |
| `lookup_number`    | Looks up carrier and line-type information for a phone number. Parameters: `number` (str, E.164 format). Returns a dictionary with the number's `number`, `country`, `format`, and `carrier`.                                                                                             |

## Developer Resources

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/plivo.py)