---
canonical_url: "https://docs.composio.dev/toolkits/plivo"
markdown_url: "https://docs.composio.dev/toolkits/plivo.md"
product: "platform"
version: null
last_updated: null
---

# Plivo

Plivo provides programmable voice, messaging, phone number, SIP, verification, and communications APIs.

- **Category:** communication
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 6
- **Triggers:** 0
- **Slug:** `PLIVO`
- **Version:** 00000000_00

## Tools

### Get Account Details

**Slug:** `PLIVO_GET_ACCOUNT_DETAILS`

Return billing, credit, timezone, and account-type details for the connected Plivo account. Use this to inspect account status and configuration before querying communication resources.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Message

**Slug:** `PLIVO_GET_MESSAGE`

Retrieve one existing Plivo message by its message UUID, including delivery, routing, timing, error, and billing details when available.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message_uuid` | string | Yes | Plivo message UUID, typically obtained from List Messages or a send response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage Summary

**Slug:** `PLIVO_GET_USAGE_SUMMARY`

Return one page of Plivo spend and usage grouped by hour, day, month, or year for a required date range, with optional usage filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `product` | array | No | Filter by one or more products: message, voice, zentrunk, transcription, or other. Omit to include all products. |
| `to_date` | string | Yes | Exclusive end of the usage range in YYYY-MM-DD format; rows at or after this date are excluded. |
| `direction` | string ("inbound" | "outbound") | No | Filter by traffic direction: inbound or outbound. |
| `from_date` | string | Yes | Inclusive start of the usage range in YYYY-MM-DD format. |
| `page_size` | integer | No | Maximum usage records in this page (1-1000). |
| `error_code` | string | No | Only include usage associated with this provider error code. |
| `subaccount` | string | No | Only include usage for this Plivo subaccount Auth ID. |
| `country_iso` | string | No | Filter by destination country ISO code. |
| `granularity` | string ("hour" | "day" | "month" | "year") | Yes | Time grouping for usage records: hour (maximum 7-day window), day (92 days), month (24 months), or year (retention-limited). |
| `hangup_cause` | string | No | Only include voice usage associated with this hangup cause. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Calls

**Slug:** `PLIVO_LIST_CALLS`

Return one page of Plivo call history, optionally filtered by time, direction, status, participants, hangup details, parent call, or subaccount. This does not initiate or modify calls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum calls in this page (1-20). |
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `status` | string | No | Filter by the provider's call status value. |
| `end_time` | string | No | Inclusive upper bound for call end time, in a Plivo-supported timestamp format. |
| `to_number` | string | No | Only return calls placed to this number. |
| `start_time` | string | No | Inclusive lower bound for call end time, in a Plivo-supported timestamp format. |
| `subaccount` | string | No | Only return calls belonging to this Plivo subaccount Auth ID. |
| `from_number` | string | No | Only return calls originating from this number. |
| `hangup_source` | string ("customer" | "carrier" | "zentrunk") | No | Filter by hangup source: customer, carrier, or zentrunk. |
| `call_direction` | string ("inbound" | "outbound") | No | Filter by call direction: inbound or outbound. |
| `parent_call_uuid` | string | No | Only return child calls associated with this parent call UUID. |
| `hangup_cause_code` | string | No | Filter calls by Plivo hangup cause code. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Messages

**Slug:** `PLIVO_LIST_MESSAGES`

Return one page of inbound and outbound Plivo message history, optionally filtered by time, direction, state, sender, recipient, type, or subaccount. This reads existing message records and does not send a message.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum messages in this page (1-20). |
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `end_time` | string | No | Inclusive upper bound for message time in Plivo's accepted timestamp format. |
| `to_number` | string | No | Only return messages sent to this phone number. |
| `start_time` | string | No | Inclusive lower bound for message time in Plivo's accepted timestamp format. |
| `subaccount` | string | No | Only return messages belonging to this Plivo subaccount Auth ID. |
| `from_number` | string | No | Only return messages sent from this phone number. |
| `message_type` | string ("sms" | "mms" | "whatsapp") | No | Filter by message type: sms, mms, or whatsapp. |
| `message_state` | string ("queued" | "sent" | "delivered" | "undelivered" | "failed" | "received") | No | Filter by message state: queued, sent, delivered, undelivered, failed, or received. |
| `message_direction` | string ("inbound" | "outbound") | No | Filter by message direction: inbound or outbound. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Owned Numbers

**Slug:** `PLIVO_LIST_OWNED_NUMBERS`

Return one page of phone numbers currently owned by the connected Plivo account, optionally filtered by prefix, type, service, alias, or subaccount.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `alias` | string | No | Filter by the number's configured alias. |
| `limit` | integer | No | Maximum owned numbers in this page (1-20). |
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `services` | string | No | Filter by enabled services using voice, sms, mms, or a provider-supported combination of those values. |
| `subaccount` | string | No | Only return numbers associated with this Plivo subaccount Auth ID. |
| `number_type` | string ("local" | "mobile" | "fixed" | "national" | "tollfree") | No | Filter by number type: local, mobile, fixed, national, or tollfree. |
| `number_startswith` | string | No | Only return owned numbers beginning with this digit prefix. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |