Add an RCS agent

Asks for an RCS agent and records the order form the carriers vet it against. Always 202: an agent is approved by the carriers, not by this call, and nothing here can make that happen sooner.

What it asks for

The RCS Agent Order Form — the same one our team fills in on your behalf today, so nothing has to be collected from you twice. All fields are required and must be submitted together so the carrier review has everything it needs. The only exception is opt_in_screenshot_url.

Agent identity: display_name, description, agent_use_case (must be one of the accepted use cases; the error names the set), brand_color (six-digit hex, #RRGGBB).

Brand identity: brand_name — the brand this agent presents. Not taken from compliance.brand: a business may present a different brand on RCS than the one its 10DLC registration is filed against, and the carriers vet this one. privacy_policy_url, terms_and_conditions_url, website_url, logo_url, and banner_url must be absolute http(s) URLs that the carriers can fetch without authentication. The form specifies 224×224 px and 50 KB for the logo and 1440×448 px and 200 KB for the banner; these cannot be checked without the image bytes.

Contact details: brand_phone_number, customer_support_phone_number, brand_email, customer_support_email, contact_name_and_title.

Company: company_ein, entity_type, official_address (street, city, state, postal_code, country), brief_company_description.

Consent and messages: opt_in_process_description, start_message, help_message, stop_message, sample_messages (at least one example message).

Optional: opt_in_screenshot_url (validated as an http(s) URL if supplied).

Anything supplied is checked against accepted values rather than passed through: a value the provider rejects would otherwise surface days later, to somebody who cannot fix it without asking you.

A customer has one agent. Asking again while you have one is 409.

What comes back, and what does not

Returns the agent — the form as stored, plus id and status. Not your other channels, which this call cannot have changed.

status is PROVISIONING until the agent is handed to the carriers and approved. GET /v3/channels reports rcs: null until then — a channel row is what routing reads to decide you are sendable, and writing one for an unapproved agent would claim a channel that cannot carry traffic.

Send x-profile-id with an organization key to ask for one of your profiles' agents.

POST
/v3/channels/rcs

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v3/channels/rcs" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "display_name": "Example Retail",    "description": "Order and delivery notifications for Example Retail customers.",    "agent_use_case": "NOTIFICATIONS",    "brand_name": "Example Retail",    "privacy_policy_url": "https://example.com/privacy",    "terms_and_conditions_url": "https://example.com/terms",    "website_url": "https://example.com",    "brand_color": "#1a73e8",    "logo_url": "https://example.com/assets/logo-224x224.png",    "banner_url": "https://example.com/assets/banner-1440x448.png",    "brand_phone_number": "+12125550100",    "customer_support_phone_number": "+18005550100",    "brand_email": "hello@example.com",    "customer_support_email": "support@example.com",    "contact_name_and_title": "Jane Smith, Head of Marketing",    "company_ein": "12-3456789",    "entity_type": "PRIVATE_PROFIT",    "official_address": {      "street": "123 Main St",      "city": "New York",      "state": "NY",      "postal_code": "10001",      "country": "US"    },    "brief_company_description": "Example Retail sells home goods across the US and ships to 48 states.",    "opt_in_process_description": "Customers opt in at checkout by checking the SMS/RCS notifications box.",    "start_message": "Welcome to Example Retail! Reply HELP for help or STOP to opt out.",    "help_message": "For help, visit https://example.com/support or call 1-800-555-0100.",    "stop_message": "You have been unsubscribed from Example Retail notifications.",    "sample_messages": [      "Your order #12345 has shipped and will arrive tomorrow."    ],    "sandbox": false  }'
{
  "success": true,
  "data": {
    "id": "c87b77eb-d936-497f-b662-a865a35d802c",
    "status": "PROVISIONING",
    "reason_code": "CHANNEL_011",
    "reason": "This channel is being set up",
    "display_name": "Example Retail",
    "description": "Order and delivery notifications for Example Retail customers.",
    "agent_use_case": "NOTIFICATIONS",
    "brand_name": "Example Retail",
    "privacy_policy_url": "https://example.com/privacy",
    "terms_and_conditions_url": "https://example.com/terms",
    "website_url": "https://example.com",
    "brand_color": "#1a73e8",
    "brand_phone_number": "+12125550100",
    "customer_support_phone_number": "+18005550100",
    "brand_email": "hello@example.com",
    "customer_support_email": "support@example.com",
    "contact_name_and_title": "Jane Smith, Head of Marketing",
    "company_ein": "12-3456789",
    "entity_type": "PRIVATE_PROFIT",
    "official_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "brief_company_description": "Example Retail sells home goods across the US and ships to 48 states.",
    "opt_in_process_description": "Customers opt in at checkout by checking the SMS/RCS notifications box.",
    "start_message": "Welcome to Example Retail! Reply HELP for help or STOP to opt out.",
    "help_message": "For help, visit https://example.com/support or call 1-800-555-0100.",
    "stop_message": "You have been unsubscribed from Example Retail notifications.",
    "sample_messages": [
      "Your order #12345 has shipped and will arrive tomorrow."
    ],
    "created_at": "2025-06-01T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_7D5fRp1sSw",
    "timestamp": "2025-06-01T12:00:00+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_001",
    "message": "brand_name is required",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7D5fRp1sSw",
    "timestamp": "2025-06-01T12:00:00+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": true,
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "doc_url": "string"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "version": "string"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_007",
    "message": "This customer already has an RCS agent. An agent cannot be withdrawn through the API once asked for, so contact support to change or replace it.",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7D5fRp1sSw",
    "timestamp": "2025-06-01T12:00:00+00:00",
    "version": "v3"
  }
}
{
  "success": true,
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "doc_url": "string"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "version": "string"
  }
}

Add a WhatsApp account POST

Connects a WhatsApp Business Account shared with us through a Multi-Partner Solution to the calling sender profile. Send `x-profile-id` for the profile the account belongs to. **Two fields, because everything else is derived.** `waba_id` says which of your organization's shared accounts this is — you hold one per client, and nothing else can say which. `phone_number_id` says which number on it to send from — an account may hold several, and choosing for you would mean deciding which of your customer's numbers their traffic leaves from. The solution the account arrived through, the client business portfolio that owns it, the access token and its expiry are all resolved from your organization. They are not accepted here: the first two are Meta's answer about provenance, and the token is minted per client business and rotates roughly every sixty days, so a value you sent would be stale before it was useful. `phone_number_id` is optional. Omit it to connect the account now and settle the number later — the channel reads as `provisioning` and the profile keeps sending from your organization's account until a number is named. The same resolution runs behind `channels.whatsapp` on `POST /v3/sender-profiles`, so connecting at create and connecting afterwards fill the same fields. Returns **the account**, not every channel you have — adding one cannot change a market or an RCS agent, and `GET /v3/channels` is the whole picture. Giving an account up is not self-service: ask support, because deregistering a number lands in your own Meta business.

Voice Callback Contract

Reference for the questions Sent POSTs to a voice number's callback URL and the answers your backend returns: the envelope, call.request and call.input, every action and instruction, parsing rules, account rules, and error reasons.