Vobiz RCS Senders and Templates

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 and /senders/{id}/templates.

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.

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.

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"}
  }'

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"])

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);

The response is 201 with the sender object:

{
  "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 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} returns the stored sender without contacting the platform. GET /senders lists your senders with limit (default 20, up to 100) and offset.

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.

Send from a sender

Once the sender is approved, pass its senderName as from with channel: rcs on POST /messages. The RCS channel guide covers suggestions (buttons), media and failoverToSms.

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

Update a sender

PUT /senders/{id} 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.

cURL

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`	`201` with the template object
List	`GET /senders/{senderId}/templates`	`200` array; `limit` (default 20) and `offset`
Get	`GET /senders/{senderId}/templates/{templateName}`	`200` with the template object
Refresh status	`GET /senders/{senderId}/templates/{templateName}/status`	`200` with the template object and refreshed `status`
Delete	`DELETE /senders/{senderId}/templates/{templateName}`	`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).

cURL

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:

{
  "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.

Getting Started

API Reference

Guides

Vobiz RCS Senders and Templates

How a sender appears on a phone

Create a sender

Review and status

Send from a sender

Update a sender

Templates

Errors

Next steps

RCS channel

RCS reachability

Before you go live

Sending RCS

Compliance overview

​How a sender appears on a phone

​Create a sender

​Review and status

​Send from a sender

​Update a sender

​Templates

​Errors

​Next steps

RCS channel

RCS reachability

​Before you go live

Sending RCS

Compliance overview

How a sender appears on a phone

Create a sender

Review and status

Send from a sender

Update a sender

Templates

Errors

Next steps

Before you go live