> For the complete documentation index, see [llms.txt](https://playbook.nativemsg.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://playbook.nativemsg.com/mcp/tool-reference/messaging.md).

# Messaging & Templates

Direct sends to specific contacts. Every send tool delivers a real message to each recipient's phone, may incur per-message charges, and **cannot be recalled** — AI clients surface these as destructive actions and ask for confirmation. For broadcasts to tagged audiences, use [Blasts](/mcp/tool-reference/blasts.md).

All send tools take `human_ids` (recipients) and optional `channel_ids` (restrict delivery; omitted = each contact's subscribed channels), and return a `requestId` for delivery tracking.

## Sending

| Tool                             | Sends                           | Key inputs                                                                                                                                             |
| -------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `send_rcs_text_message`          | Plain text                      | `text` (1–1600 chars)                                                                                                                                  |
| `send_rcs_media_message`         | Image / audio / video / file    | `media_url` (HTTPS; cached 30 days), `media_type`, optional `text` caption                                                                             |
| `send_rcs_buttons_message`       | Text + action buttons (≤11)     | `text`, `buttons` (`type`: URL, DIAL, VIEW\_LOCATION, SHARE\_LOCATION, CALENDAR\_EVENT; plus type-specific fields)                                     |
| `send_rcs_quick_replies_message` | Text + tap-to-reply chips (≤11) | `text`, `quick_replies` (`{ text, postbackData }`)                                                                                                     |
| `send_rcs_rich_card_message`     | One rich card                   | `rich_card` (`title`, `description`, `media`, `suggestions`; one of media/title required)                                                              |
| `send_rcs_carousel_message`      | Swipeable cards (2–10)          | `carousel` (cards with `title`, `description`, `media`, `suggestions`)                                                                                 |
| `send_rcs_list_message`          | Sectioned list                  | `list_items`                                                                                                                                           |
| `send_message_from_template`     | A saved template                | `template_id`                                                                                                                                          |
| `schedule_text_message`          | Plain text at a future time     | `text`, `scheduled_date_iso` (`yyyy-MM-ddTHH:mm:ss±hh:mm`, applied verbatim), `misfire_type` (0 = drop if late, 1 = fire late within `misfire_period`) |

Rich-message *scheduling* (carousel, rich card, etc.) is dashboard-only today; the MCP tool schedules text. To schedule rich content to an audience, use a [blast](/mcp/tool-reference/blasts.md).

## Delivery status

| Tool                 | What it does                                                                                                                                                                                                  | Key inputs           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `get_message_status` | All messages produced by one send request (one row per recipient): `status` (accepted, pending, sent, delivered, failed, queued, read), `messageType` (outbound/inbound/blast), `delivered`, original payload | `request_id`, paging |
| `get_message`        | One message by numeric id                                                                                                                                                                                     | `message_id`         |

## Templates

Saved messages reusable in `send_message_from_template` and blasts.

| Tool                      | What it does                                                                                          | Key inputs            |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------- |
| `list_message_templates`  | `id`, `name`, `readOnly` (true = system template), dates                                              | paging                |
| `get_message_template`    | One template including its saved message                                                              | `template_id`         |
| `create_message_template` | Save a Message Object (`text`, `media`, `buttons`, `quickReplies`, `carousel`, …) under a name (≤260) | `name`, `message`     |
| `update_message_template` | Rename or replace the saved message. System templates cannot change                                   | `template_id`, fields |
| `delete_message_template` | Delete (cannot be undone; system templates protected)                                                 | `template_id`         |

## Notes

* **Check capability before rich sends:** `check_rcs_capability` tells you whether a recipient's device supports rich cards/carousels; non-RCS devices get SMS fallback.
* **Test first:** send to a tester device (`add_tester_device`) and verify rendering on a real phone before messaging customers.
* Media URLs are cached for 30 days, then re-downloaded on the next send.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://playbook.nativemsg.com/mcp/tool-reference/messaging.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.