> ## 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 RCS Senders and Templates

> Create and manage RCS senders (agents) on Vobiz - the verified brand identity with name, logo, colour and contact links that appears in the recipient's messaging app - and the message templates attached to them.

RCS messages are sent from a **sender** (also called an agent): a verified business identity that the recipient's messaging app displays instead of a phone number. A sender carries your brand name, logo, banner, accent colour, description and contact links. The RCS platform and the carriers review a sender before it can message real users.

In the console, senders live under **SMS & RCS → RCS agents**. This page covers the same resources through the API: [`/senders`](/docs/sms/api/senders/create-sender) and [`/senders/{id}/templates`](/docs/sms/api/senders/create-template).

## How a sender appears on a phone

When your message arrives, the conversation header shows the sender's display name next to its logo, with a verified badge once the sender is approved. Opening the sender's profile shows the banner image, the description, the tap-to-call phone numbers, email addresses and website links you registered, and links to your privacy policy and terms. Buttons and cards in your messages use the sender's colour as their accent. Because the identity is verified, recipients see a business they can look up rather than an unknown number.

## Create a sender

Send these fields on [`POST /senders`](/docs/sms/api/senders/create-sender).

| Field | Type | Required | Description |
| - | - | - | - |
| `provider` | string | yes | The routing identifier your account was provisioned with. Contact support if you are unsure which value to use. |
| `senderName` | string | yes | Unique technical name for the sender. Fixed after creation. |
| `displayName` | string | | The name shown in the conversation header. |
| `description` | string | | Short description shown in the sender's profile. |
| `billingCategory` | string | | `CONVERSATIONAL` or `NON_CONVERSATIONAL`. |
| `useCase` | string | | `OTP`, `TRANSACTIONAL`, `PROMOTIONAL` or `MULTI_USE`. |
| `hostingRegion` | string | | `NORTH_AMERICA`, `EUROPE` or `ASIA_PACIFIC`. Fixed after creation. |
| `brand` | object | | `{"brandName": "Acme"}`. |
| `color` | string | | Accent colour as a hex value, for example `#0A7CFF`. |
| `phones` | array | | `[{"phoneNumber": "+14155550100", "label": "Support"}]`. |
| `emails` | array | | `[{"address": "support@example.com", "label": "Support"}]`. |
| `websites` | array | | `[{"url": "https://example.com", "label": "Website"}]`. |
| `logoUrl` | string | | Public URL of the square logo. |
| `bannerUrl` | string | | Public URL of the wide banner image. |
| `privacy` | object | | `{"url": "https://example.com/privacy", "label": "Privacy policy"}`. |
| `termsOfService` | object | | `{"url": "https://example.com/terms", "label": "Terms of service"}`. |
| `platform` | object | | `{"applicationId": "...", "entityId": "..."}` where your RCS platform setup requires them. |

The enum values for `billingCategory`, `useCase` and `hostingRegion` are the values the RCS platform accepts; Vobiz passes them through as you send them.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.vobiz.ai/api/v1/sms/senders" \
    -H "X-Auth-ID: MA_XXXXXXXX" \
    -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "YOUR_PROVISIONED_ROUTING_ID",
      "senderName": "acme-support",
      "displayName": "Acme Support",
      "description": "Order updates and support from Acme.",
      "billingCategory": "CONVERSATIONAL",
      "useCase": "MULTI_USE",
      "hostingRegion": "NORTH_AMERICA",
      "brand": {"brandName": "Acme"},
      "color": "#0A7CFF",
      "logoUrl": "https://example.com/brand/logo-224.png",
      "bannerUrl": "https://example.com/brand/banner-1440x448.png",
      "phones": [{"phoneNumber": "+14155550100", "label": "Support"}],
      "emails": [{"address": "support@example.com", "label": "Support"}],
      "websites": [{"url": "https://example.com", "label": "Website"}],
      "privacy": {"url": "https://example.com/privacy", "label": "Privacy policy"},
      "termsOfService": {"url": "https://example.com/terms", "label": "Terms of service"}
    }'
  ```

  ```python Python theme={null}
  import requests

  BASE = "https://api.vobiz.ai/api/v1/sms"
  HEADERS = {
      "X-Auth-ID": "MA_XXXXXXXX",
      "X-Auth-Token": "YOUR_AUTH_TOKEN",
      "Content-Type": "application/json",
  }

  sender = {
      "provider": "YOUR_PROVISIONED_ROUTING_ID",
      "senderName": "acme-support",
      "displayName": "Acme Support",
      "description": "Order updates and support from Acme.",
      "billingCategory": "CONVERSATIONAL",
      "useCase": "MULTI_USE",
      "hostingRegion": "NORTH_AMERICA",
      "brand": {"brandName": "Acme"},
      "color": "#0A7CFF",
      "logoUrl": "https://example.com/brand/logo-224.png",
      "bannerUrl": "https://example.com/brand/banner-1440x448.png",
      "phones": [{"phoneNumber": "+14155550100", "label": "Support"}],
      "emails": [{"address": "support@example.com", "label": "Support"}],
      "websites": [{"url": "https://example.com", "label": "Website"}],
      "privacy": {"url": "https://example.com/privacy", "label": "Privacy policy"},
      "termsOfService": {"url": "https://example.com/terms", "label": "Terms of service"},
  }

  r = requests.post(f"{BASE}/senders", headers=HEADERS, json=sender)
  r.raise_for_status()
  print(r.json()["id"], r.json()["status"])
  ```

  ```javascript Node theme={null}
  const BASE = "https://api.vobiz.ai/api/v1/sms";
  const headers = {
    "X-Auth-ID": "MA_XXXXXXXX",
    "X-Auth-Token": "YOUR_AUTH_TOKEN",
    "Content-Type": "application/json",
  };

  const sender = {
    provider: "YOUR_PROVISIONED_ROUTING_ID",
    senderName: "acme-support",
    displayName: "Acme Support",
    description: "Order updates and support from Acme.",
    billingCategory: "CONVERSATIONAL",
    useCase: "MULTI_USE",
    hostingRegion: "NORTH_AMERICA",
    brand: { brandName: "Acme" },
    color: "#0A7CFF",
    logoUrl: "https://example.com/brand/logo-224.png",
    bannerUrl: "https://example.com/brand/banner-1440x448.png",
    phones: [{ phoneNumber: "+14155550100", label: "Support" }],
    emails: [{ address: "support@example.com", label: "Support" }],
    websites: [{ url: "https://example.com", label: "Website" }],
    privacy: { url: "https://example.com/privacy", label: "Privacy policy" },
    termsOfService: { url: "https://example.com/terms", label: "Terms of service" },
  };

  const res = await fetch(`${BASE}/senders`, {
    method: "POST",
    headers,
    body: JSON.stringify(sender),
  });
  if (!res.ok) throw new Error(await res.text());
  const created = await res.json();
  console.log(created.id, created.status);
  ```
</CodeGroup>

The response is `201` with the sender object:

```json theme={null}
{
  "id": "5d2f8a61-3c4b-4e7d-9f0a-2b1c3d4e5f60",
  "accountId": "MA_XXXXXXXX",
  "provider": "YOUR_PROVISIONED_ROUTING_ID",
  "senderName": "acme-support",
  "displayName": "Acme Support",
  "description": "Order updates and support from Acme.",
  "billingCategory": "CONVERSATIONAL",
  "useCase": "MULTI_USE",
  "hostingRegion": "NORTH_AMERICA",
  "status": "pending",
  "brand": {"brandName": "Acme"},
  "color": "#0A7CFF",
  "phones": [{"phoneNumber": "+14155550100", "label": "Support"}],
  "emails": [{"address": "support@example.com", "label": "Support"}],
  "websites": [{"url": "https://example.com", "label": "Website"}],
  "logoUrl": "https://example.com/brand/logo-224.png",
  "bannerUrl": "https://example.com/brand/banner-1440x448.png",
  "privacy": {"url": "https://example.com/privacy", "label": "Privacy policy"},
  "termsOfService": {"url": "https://example.com/terms", "label": "Terms of service"},
  "createdAt": "2026-10-12T10:30:00.123456Z",
  "updatedAt": "2026-10-12T10:30:00.123456Z"
}
```

`provider` in responses is an internal routing identifier; do not rely on its value.

## Review and status

The RCS platform and the carriers review the sender's identity and assets. [`GET /senders/{id}/status`](/docs/sms/api/senders/get-sender-status) asks the platform for the current launch state, stores it on the sender and returns the sender object with the refreshed `status`. A new sender starts as `pending`; the value is the platform's own status string, so display it as text rather than matching a fixed list.

[`GET /senders/{id}`](/docs/sms/api/senders/get-sender) returns the stored sender without contacting the platform. [`GET /senders`](/docs/sms/api/senders/list-senders) lists your senders with `limit` (default 20, up to 100) and `offset`.

<Note>
  Review time depends on the RCS platform and the carriers in each market. Create the sender well before you plan to launch, and prepare a logo, a banner and live privacy and terms pages that match the brand name.
</Note>

## Send from a sender

Once the sender is approved, pass its `senderName` as `from` with `channel: rcs` on [`POST /messages`](/docs/sms/api/messages/send-message). The [RCS channel guide](/docs/sms/channels/rcs) covers suggestions (buttons), media and `failoverToSms`.

```json theme={null}
{
  "from": "acme-support",
  "to": ["+14155550123"],
  "channel": "rcs",
  "text": "Acme: Your order #4821 has shipped.",
  "failoverToSms": true
}
```

## Update a sender

[`PUT /senders/{id}`](/docs/sms/api/senders/update-sender) takes any subset of `displayName`, `description`, `billingCategory`, `useCase`, `brand`, `color`, `phones`, `emails`, `websites`, `bannerUrl`, `logoUrl`, `privacy`, `termsOfService` and `platform`. Fields you omit keep their value. `provider`, `senderName` and `hostingRegion` are fixed at creation. The response is `200` with the updated sender.

```bash cURL theme={null}
curl -X PUT "https://api.vobiz.ai/api/v1/sms/senders/5d2f8a61-3c4b-4e7d-9f0a-2b1c3d4e5f60" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Order updates, returns and support from Acme.", "color": "#1E66F5"}'
```

## Templates

A template is a reusable message layout registered under a sender. Templates are reviewed by the RCS platform like the sender itself.

| Action | Endpoint | Result |
| - | - | - |
| Create | [`POST /senders/{senderId}/templates`](/docs/sms/api/senders/create-template) | `201` with the template object |
| List | [`GET /senders/{senderId}/templates`](/docs/sms/api/senders/list-templates) | `200` array; `limit` (default 20) and `offset` |
| Get | [`GET /senders/{senderId}/templates/{templateName}`](/docs/sms/api/senders/get-template) | `200` with the template object |
| Refresh status | [`GET /senders/{senderId}/templates/{templateName}/status`](/docs/sms/api/senders/get-template-status) | `200` with the template object and refreshed `status` |
| Delete | [`DELETE /senders/{senderId}/templates/{templateName}`](/docs/sms/api/senders/delete-template) | `204`, no body |

The create body has three fields: `templateName` (unique under the sender, used in the URL of the other calls), `type` (the template type as defined by the RCS platform) and `content` (an object in the platform's template structure for that type).

```bash cURL theme={null}
curl -X POST "https://api.vobiz.ai/api/v1/sms/senders/5d2f8a61-3c4b-4e7d-9f0a-2b1c3d4e5f60/templates" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "order-shipped",
    "type": "TEXT",
    "content": {
      "text": "Acme: Your order {{orderId}} has shipped. Track it at {{trackingUrl}}."
    }
  }'
```

The template object:

```json theme={null}
{
  "id": "7e3a9b52-1d6c-4f8e-a0b1-c2d3e4f5a601",
  "senderId": "5d2f8a61-3c4b-4e7d-9f0a-2b1c3d4e5f60",
  "accountId": "MA_XXXXXXXX",
  "provider": "YOUR_PROVISIONED_ROUTING_ID",
  "templateName": "order-shipped",
  "type": "TEXT",
  "status": "pending",
  "content": {
    "text": "Acme: Your order {{orderId}} has shipped. Track it at {{trackingUrl}}."
  },
  "createdAt": "2026-10-12T10:35:00.000000Z",
  "updatedAt": "2026-10-12T10:35:00.000000Z"
}
```

## Errors

Sender and template calls report problems as `400 {"error": "<message>"}`, with the message text describing the cause. Typical messages:

| Message | Cause |
| - | - |
| `provider not found: provider "" not found` | `provider` missing or not one your account is provisioned with. Contact support for the value to use. |
| `provider create sender failed: ...` | The RCS platform rejected the sender. The rest of the text explains why: missing asset, duplicate `senderName`, invalid colour. |
| `sender not found` | Unknown `senderId` on a template call. |
| `provider create template failed: ...` | The platform rejected the template `type` or `content`. |

`GET /senders/{id}` and `GET /senders/{senderId}/templates/{templateName}` return `404 {"error": "sender not found"}` or `{"error": "template not found"}` for unknown ids. See the [error reference](/docs/sms/errors).

## Next steps

<CardGroup cols={2}>
  <Card title="RCS channel" icon="sparkles" href="/docs/sms/channels/rcs">
    Rich messages, suggestions and SMS fallback.
  </Card>

  <Card title="RCS reachability" icon="signal" href="/docs/sms/api/messages/rcs-reachability">
    Check whether a number can receive RCS before you send.
  </Card>
</CardGroup>

## Before you go live

<CardGroup cols={2}>
  <Card title="Sending RCS" icon="sparkles" href="/docs/sms/channels/rcs">
    Buttons, media and SMS fallback.
  </Card>

  <Card title="Compliance overview" icon="shield-check" href="/docs/sms/compliance/overview">
    Registration for the numbers behind SMS fallback.
  </Card>
</CardGroup>


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