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

# Vobiz Messaging API - RCS Senders

> The Vobiz RCS Senders API registers the branded RCS agent your messages come from, tracks its launch status on the RCS platform, and manages the message templates attached to it.

An RCS sender (also called an agent) is the verified business identity that a recipient's messaging app shows instead of a phone number: your brand name, logo, banner, colour, description and contact links. You create a sender once, wait for the RCS platform to launch it, and then send RCS messages from it. Each sender can also hold message templates that the RCS platform reviews and approves.

## The sender object

| Field | Type | Description |
| - | - | - |
| `id` | string (UUID) | Unique identifier on Vobiz. Use it in every `/senders/{id}` path. |
| `accountId` | string | Your Vobiz account ID (`MA_...`). |
| `provider` | string | Internal routing identifier; do not rely on its value. |
| `senderName` | string | Unique technical name on the RCS platform. Pass it as `from` when you send RCS. Fixed after creation. |
| `displayName` | string | The brand name recipients see at the top of the conversation. |
| `description` | string | Short description shown on the sender's info page. |
| `billingCategory` | string | How the RCS platform bills conversations, for example `CONVERSATIONAL` or `NON_CONVERSATIONAL`. |
| `useCase` | string | Kind of traffic, for example `OTP`, `TRANSACTIONAL`, `PROMOTIONAL` or `MULTI_USE`. |
| `hostingRegion` | string | Where the RCS platform hosts the sender, for example `NORTH_AMERICA`, `EUROPE` or `ASIA_PACIFIC`. Fixed after creation. |
| `status` | string | Launch status reported by the RCS platform. `pending` until the platform reports otherwise. |
| `brand` | object | `{ "brandName": "..." }`. |
| `color` | string | Accent colour as a hex code, such as `#1A73E8`. |
| `phones`, `emails`, `websites` | array | Labelled contact entries shown on the sender's info page. |
| `bannerUrl`, `logoUrl` | string | Public HTTPS URLs of the banner and logo images. |
| `privacy`, `termsOfService` | object | Labelled links: `{ "url": "...", "label": "..." }`. |
| `platform` | object | `applicationId` and `entityId` the RCS platform assigned to your agent, when you have them. |
| `createdAt`, `updatedAt` | string | ISO 8601 timestamps (UTC). |

## The template object

| Field | Type | Description |
| - | - | - |
| `id` | string (UUID) | Unique identifier on Vobiz. |
| `senderId` | string (UUID) | The sender the template belongs to. |
| `templateName` | string | Unique name on the sender. Template endpoints address templates by this name. |
| `type` | string | Template type as defined by the RCS platform. |
| `status` | string | Approval status reported by the RCS platform. |
| `content` | object | The template content exactly as you submitted it. |
| `createdAt`, `updatedAt` | string | ISO 8601 timestamps (UTC). |

## Endpoints

| Method | Endpoint | What it does |
| - | - | - |
| `POST` | [`/senders`](/docs/sms/api/senders/create-sender) | Register a new RCS sender. |
| `GET` | [`/senders`](/docs/sms/api/senders/list-senders) | List the senders on your account. |
| `GET` | [`/senders/{id}`](/docs/sms/api/senders/get-sender) | Retrieve one sender. |
| `PUT` | [`/senders/{id}`](/docs/sms/api/senders/update-sender) | Update a sender's profile. |
| `GET` | [`/senders/{id}/status`](/docs/sms/api/senders/get-sender-status) | Refresh the sender's launch status from the RCS platform. |
| `POST` | [`/senders/{senderId}/templates`](/docs/sms/api/senders/create-template) | Register a template on a sender. |
| `GET` | [`/senders/{senderId}/templates`](/docs/sms/api/senders/list-templates) | List a sender's templates. |
| `GET` | [`/senders/{senderId}/templates/{templateName}`](/docs/sms/api/senders/get-template) | Retrieve one template. |
| `DELETE` | [`/senders/{senderId}/templates/{templateName}`](/docs/sms/api/senders/delete-template) | Delete a template. |
| `GET` | [`/senders/{senderId}/templates/{templateName}/status`](/docs/sms/api/senders/get-template-status) | Refresh the template's approval status from the RCS platform. |

## From creation to sending

<Steps>
  <Step title="Create the sender">
    Call `POST /senders` with `provider`, `senderName` and the profile recipients will see. The sender starts as `pending`.
  </Step>

  <Step title="Wait for launch">
    The RCS platform and the carriers review the sender. Poll `GET /senders/{id}/status`, which asks the platform for the current state and stores it.
  </Step>

  <Step title="Send RCS">
    Once the sender is live, call `POST /messages` with `channel: rcs` and the sender's `senderName` as `from`.
  </Step>
</Steps>

## Stored and refreshed status

`GET /senders`, `GET /senders/{id}` and the template reads return the `status` stored on your account. The two `/status` endpoints ask the RCS platform for the current state, store it and return the updated object. Poll a `/status` endpoint while you wait for a launch or an approval, and use the plain reads everywhere else.

## Fixed and editable fields

`provider`, `senderName` and `hostingRegion` are set when you create the sender and cannot be changed. Every other profile field can be updated with `PUT /senders/{id}`; send only the fields you want to change. Template `type` and `content` are passed to the RCS platform unchanged, so use the shapes the platform defines for the type you choose.

## Pagination

`GET /senders` and `GET /senders/{senderId}/templates` take `limit` (1 to 100, default 20) and `offset` (default 0). Both return a bare JSON array with no total count; an empty array means you have reached the end.

## Example

Refresh a sender's launch status:

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/senders/9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01/status" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

```json Response theme={null}
{
  "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
  "accountId": "MA_XXXXXXXX",
  "provider": "YOUR_ROUTING_IDENTIFIER",
  "senderName": "acme_support",
  "displayName": "Acme Support",
  "description": "Order updates and support from Acme.",
  "billingCategory": "CONVERSATIONAL",
  "useCase": "TRANSACTIONAL",
  "hostingRegion": "NORTH_AMERICA",
  "status": "pending",
  "color": "#1A73E8",
  "logoUrl": "https://example.com/logo.png",
  "createdAt": "2026-10-12T10:30:00Z",
  "updatedAt": "2026-10-12T11:05:00Z"
}
```

## Related

* [RCS senders guide](/docs/sms/rcs-senders) - designing the profile and walking a sender through review.
* [RCS channel](/docs/sms/channels/rcs) - sending rich messages, suggestions and SMS failover.
* [Send a message](/docs/sms/api/messages/send-message) - the endpoint you send RCS through.
* [RCS reachability](/docs/sms/api/messages/rcs-reachability) - check whether a number can receive RCS from your sender.
* [Errors](/docs/sms/errors) - error responses and how to handle them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.