Voice

Plivo Openclaw Tools

Name: Plivo Openclaw Tools
Rating: 3.5 (1 reviews)
Author: sarveshpatil-plivo

By sarveshpatil-plivo 👁 56 views ▲ 0 votes

Plivo tools plugin for OpenClaw — send SMS, place calls, number lookup, and Verify OTP as agent tools. Published on ClawHub.

GitHub

Install

npm install
npm

Configuration Example

{
  "plugins": {
    "plivo-tools": {
      "config": {
        "authId": "MA...",
        "authToken": "your-plivo-auth-token",
        "fromNumber": "+15551234567",
        "verifyAppUuid": "optional-verify-app-uuid",
        "defaultAnswerUrl": "https://xml.example.com/answer",
        "answerMethod": "GET"
      }
    }
  }
}

README

<!-- markdownlint-disable MD013 -->

# Plivo Tools for OpenClaw

Give an OpenClaw agent five Plivo capabilities as callable tools: send SMS, place a call, look up a phone number, and run a Verify one-time-passcode flow (send + check). This is a standalone tool plugin. It does not modify OpenClaw core and it does not replace the bundled SMS channels; it adds agent tools that talk to the Plivo REST API.

> **When to use this vs the Plivo SMS channel.** Install the Plivo SMS channel plugin (`plivo-openclaw-sms-channel`) if you want people to converse with your agent over SMS, meaning inbound texts and outbound replies. Install this tools plugin if you want the agent to take Plivo actions such as sending an SMS, placing a call, looking up a number, or running a Verify OTP flow, as steps inside a task. They are complementary, so install both if you want both.

## Tools

| Tool | What it does |
| --- | --- |
| `plivo_send_sms` | Send an SMS to a destination number. `POST /Message/`. |
| `plivo_make_call` | Place an outbound call answered by an answer_url returning Plivo XML. `POST /Call/`. |
| `plivo_lookup_number` | Look up carrier, country, and format details for a number. `GET lookup.plivo.com/v1/Number/`. |
| `plivo_verify_send` | Start a Verify session and send an OTP over SMS or voice. `POST /Verify/Session/`. |
| `plivo_verify_check` | Validate an OTP for a session. Fails closed: a wrong or expired code throws. `POST /Verify/Session/{uuid}/`. |

## Prerequisites

- OpenClaw `2026.5.7` or later.
- A Plivo account. Your Plivo Auth ID and Auth Token are at [cx.plivo.com](https://cx.plivo.com/?utm_source=github&utm_medium=oss&utm_campaign=plivo-openclaw-tools).
- An SMS/voice-capable Plivo number for `plivo_send_sms` and `plivo_make_call`.
- For `plivo_make_call`, an answer_url that returns Plivo XML.
- For `plivo_verify_send` and `plivo_verify_check`, a Plivo Verify Application. Set its UUID as `verifyAppUuid`, or configure a default Verify app on your account. Without one, Plivo rejects the request with `'' is not a valid app_uuid`.

## Install

From ClawHub:

```sh
openclaw plugins install clawhub:plivo-openclaw-tools
```

From source:

```sh
git clone https://github.com/sarveshpatil-plivo/plivo-openclaw-tools.git
cd plivo-openclaw-tools
npm install
npm run build
```

## Configuration

Config lives under `plugins.plivo-tools.config` in `openclaw.json`:

```json
{
  "plugins": {
    "plivo-tools": {
      "config": {
        "authId": "MA...",
        "authToken": "your-plivo-auth-token",
        "fromNumber": "+15551234567",
        "verifyAppUuid": "optional-verify-app-uuid",
        "defaultAnswerUrl": "https://xml.example.com/answer",
        "answerMethod": "GET"
      }
    }
  }
}
```

### Configuration reference

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `authId` | string | Yes | — | Plivo Auth ID from [cx.plivo.com](https://cx.plivo.com/?utm_source=github&utm_medium=oss&utm_campaign=plivo-openclaw-tools). |
| `authToken` | string | Yes | — | Plivo Auth Token. Keep it secret. |
| `fromNumber` | string | For send/call | — | Default E.164 sender used when a tool's `from` argument is omitted. |
| `verifyAppUuid` | string | For Verify | account default app | Plivo Verify application UUID used by the Verify tools. Verify needs a Verify App, so set this unless your account already has a default Verify app. |
| `defaultAnswerUrl` | string | For call | — | Default answer_url for `plivo_make_call` when `answer_url` is omitted. |
| `answerMethod` | string | No | `GET` | HTTP method used to fetch the answer_url. |

`authId` and `authToken` are validated once at load. If either is missing the plugin logs an error and registers no tools, so a call can never phantom-succeed against missing credentials.

## Security model

- Egress is SSRF-guarded and restricted to `api.plivo.com` and `lookup.plivo.com` over HTTPS.
- All requests use HTTP Basic auth built from your Auth ID and Auth Token.
- Every operation fails closed: a non-2xx response throws a structured error, and a 2xx response missing its expected identifier (message_uuid, request_uuid, session_uuid) is treated as a failure. `plivo_verify_check` never reports success for a rejected OTP.
- Keep your Auth Token in OpenClaw config or secrets, never in source control.

## Package identity

- npm package: `plivo-openclaw-tools` (unscoped).
- OpenClaw plugin id: `plivo-tools`.
- The ClawHub owner/scope (for example `@plivo` vs a personal owner) is chosen at publish time via `clawhub publish --owner` and is still pending. It is intentionally not encoded in this package.

## Get a Plivo account

Sign up at [cx.plivo.com](https://cx.plivo.com/?utm_source=github&utm_medium=oss&utm_campaign=plivo-openclaw-tools).

## Development

```sh
npm install
npm test
npm run typecheck
npm run build
```

## License

MIT

voice