{ "data": { "brand": { "id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f", "brand_name": "Acme Retail", "verification_status": "submitted" }, "bot": { "id": "bot_4kqzx1", "brand_id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f", "display_name": "Acme Alerts", "status": "pending_verification", "verification_status": "pending", "carrier_statuses": { "310260": { "status": "pending" } } } }, "meta": { "request_id": "req_01k2setupa", "timestamp": "2026-10-01T09:14:00.000Z" } }

RCS Setup Wizard: Brand and First Agent in One Form

The Messages → RCS → Setup page is a one-shot setup form for a workspace that has not registered an RCS brand yet. It collects the brand identity and the first agent (bot) together and submits both in a single request, so there is no draft-brand step to manage and no approval to wait on between the brand and the agent. Behind it sits the combined POST /api/v1/rcs/setup endpoint — one call instead of the two-step POST /api/v1/rcs/brands then POST /api/v1/rcs/bots sequence the RCS onboarding guide walks. You need an owner, admin, or developer role to open the page.

1. Where the wizard lives

Open Messages → RCS → Setup from the RCS section of the dashboard. It is the first-stop path for a brand-new workspace: when no brand exists yet, the page offers one form that registers the brand and creates the first agent on it.

2. One-shot wizard vs the split flow

Two entry points cover the same registration:

The one-shot wizard (this page). Brand and first agent in one submission, one validation pass, one success screen. Everything the agent needs it borrows from the same form — the agent logo is the brand logo. Use it for a workspace’s very first setup.
The split flow. Create the brand under Messages → RCS → Brands or with POST /api/v1/rcs/brands, then create agents with POST /api/v1/rcs/bots (or the wizard under Settings → Channels → RCS). Use it for every agent after the first, and when you want the API path the RCS onboarding guide covers.

The wizard only accepts a first setup. If the workspace already carries a brand, submitting returns 422 BRAND_ALREADY_EXISTS; from then on, later agents attach to the existing brand through the split flow. The one-shot submission runs the same brand-then-agent chain server-side: if the agent submission fails, the brand it created is rolled back, so a retry is always a clean first-setup attempt rather than a partial two-step dead-end.

3. The form, card by card

The page validates against the shared rcsSetupSchema before anything posts and names the first failing field inline — a blank submission never reaches the API.

Brand identity

Field	Notes
Brand name (required)	Up to 100 characters. Carriers see this as the business identity.
Brand website (required)	Public HTTPS site for the business.
Industry (required)	Pick from the fixed list the aggregator accepts. A name not on the list resolves to “Other”, which weakens the registered vertical.
Brand logo URL (required)	A public HTTPS URL pointing at the logo image — PNG or JPG, and a 400×400 square at around 90 KB is the recommended shape; size is a recommendation, not a rejection. Carriers refuse a brand registration without a logo, so the field is required. The same URL also serves as the first agent’s logo — the aggregator rejects an agent without one. (The Brands console create path takes the logo as a file upload instead; see the RCS brands console guide.)
Legal entity name (optional)	Add when it differs from the trade name (DBA).
Tax ID (optional)	EIN / VAT / GST / CNPJ. Some carriers require it for KYC.

Contact person

Field	Notes
First name (required)	Used by the aggregator and carriers for KYC verification calls.
Last name (required)	Same.
Email (required)	Same.
Phone, E.164 (required)	Same.
Job title (optional)	Free text.

Company address

State or province is required on every registration (up to 128 characters) — the provider’s required-field table carries it, and a missing value is refused before the form submits. Address line 1, city, country, and postal code are likewise required; address line 2 is optional. For KYC-mandatory countries (India, Brazil, and others) the full address block is screened at registration, so fill every line rather than leaving blanks for a later request. The country picker uses ISO two-letter codes.

First agent

Field	Notes
Display name (required)	What subscribers see in the chat header.
Description (required)	100 characters or fewer — the aggregator’s cap.
Agent banner image URL (required)	1440×448px. The aggregator rejects an agent submitted without a banner.
Terms of Service URL (required)	HTTPS. Carriers refuse an agent without it.
Privacy Policy URL (required)	HTTPS. Carriers refuse an agent without it.
Agent contact phone (one of phone/email required)	E.164. Verification for the agent runs against this contact.
Agent contact email (one of phone/email required)	Same.
Target carriers (MCCMNC) (required)	Five- or six-digit carrier codes separated by spaces, commas, or new lines (for example `310260` for US T-Mobile). An empty list is rejected, and a code the aggregator’s directory does not carry comes back as “Unknown carrier mccmnc”. Find operator codes on mcc-mnc.com or use the quick-add presets under Settings → Channels → RCS.

The submit button stays disabled until every required field is filled and at least one of the agent contact channels is present.

4. What the submission does

One click of Submit brand + first agent sends a single POST /api/v1/rcs/setup with everything above. The endpoint creates the brand, records it as submitted, and registers the agent with the brand bundled into the same upstream request — then returns 201 with both records. Success routes to a confirmation screen naming the brand, with shortcuts to Messages → RCS and the Brands list. A 422 response names the fields that failed validation; a provider-side failure returns its own actionable error — and either way the brand created during the attempt is rolled back, so the next submit starts clean. The logo is required here for two reasons at once: it registers the brand and doubles as the first agent’s logo, and the aggregator rejects an agent submission without one. state_province is required too (up to 128 characters) — it lands in the provider’s required state field, so a blank one is refused before the form submits. Here the logo is collected as a hosted HTTPS URL (brand_logo_url), because it is also forwarded as the first agent’s logo; the file-upload path lives on the Brands console create form (see that guide). The same combined contract is available to API-first teams:

curl -X POST https://api.orbit.devotel.io/api/v1/rcs/setup \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "Acme Retail",
    "brand_website": "https://acmeretail.com",
    "brand_logo_url": "https://acmeretail.com/assets/logo.png",
    "industry_vertical": "Shopping & retail",
    "contact_first_name": "Ada",
    "contact_last_name": "Wong",
    "contact_email": "ada.wong@acmeretail.com",
    "contact_phone": "+14155552671",
    "address_line_1": "100 Market Street",
    "city": "San Francisco",
    "country": "US",
    "postal_code": "94103",
    "display_name": "Acme Alerts",
    "description": "Order and delivery updates",
    "tos_url": "https://acmeretail.com/terms",
    "privacy_policy_url": "https://acmeretail.com/privacy",
    "banner_image_url": "https://cdn.acmeretail.com/banner.png",
    "carrier_mccmnc": ["310260"],
    "bot_contact_email": "support@acmeretail.com",
    "website": "https://acmeretail.com",
    "bot_type": "Transactional",
    "region": "Rest of World",
    "platform": "GSMA API"
  }'

The responses you branch on: 201 — brand and first agent created. data.brand is the registered brand, recorded as submitted; data.bot is the first agent, with one pending entry per MCCMNC you sent in carrier_mccmnc. Store data.bot.id — the verify, launch, and quality reads in §5 all take it.

{
  "data": {
    "brand": {
      "id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
      "brand_name": "Acme Retail",
      "verification_status": "submitted"
    },
    "bot": {
      "id": "bot_4kqzx1",
      "brand_id": "8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f",
      "display_name": "Acme Alerts",
      "status": "pending_verification",
      "verification_status": "pending",
      "carrier_statuses": {
        "310260": { "status": "pending" }
      }
    }
  },
  "meta": {
    "request_id": "req_01k2setupa",
    "timestamp": "2026-10-01T09:14:00.000Z"
  }
}

422 — the workspace already has a brand. Setup is first-setup-only; the error points you at the split flow instead of stacking a second brand:

{
  "error": {
    "code": "BRAND_ALREADY_EXISTS",
    "message": "RCS setup is a first-setup-only endpoint — this tenant already has a brand. Reuse it for later bots via POST /rcs/bots (passing its brand_id). To start over, delete the existing brand first.",
    "status": 422
  },
  "meta": {
    "request_id": "req_01k2setupb",
    "timestamp": "2026-10-01T09:14:00.000Z"
  }
}

502 — provider-side failure, nothing left behind. When the RCS directory cannot take the combined submission, the brand the attempt created (here 8f2c41ab-9d4e-4c1a-b2e0-1a2b3c4d5e6f) is rolled back before this error returns, and details.retryable marks the retry as safe: resubmitting the same body is a clean first-setup attempt, never a BRAND_ALREADY_EXISTS trap left over from the failed one. A content rejection (an unknown carrier code, a missing asset) arrives the same way as a 422 VALIDATION_ERROR whose details.rejected_reason quotes the directory’s reason — and the rollback applies there too.

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Dotgo's bot registration service is temporarily unavailable. Please try again shortly.",
    "status": 502,
    "details": {
      "retryable": true
    }
  },
  "meta": {
    "request_id": "req_01k2setupc",
    "timestamp": "2026-10-01T09:14:00.000Z"
  }
}

Poll for the verdict. Right after setup, GET /api/v1/rcs/bots/:id/quality reads:

curl https://api.orbit.devotel.io/api/v1/rcs/bots/bot_4kqzx1/quality \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "bot_id": "bot_4kqzx1",
    "display_name": "Acme Alerts",
    "brand_name": "Acme Retail",
    "status": "pending_verification",
    "verification_status": "pending",
    "launched": false,
    "carrier_statuses": { "310260": { "status": "pending" } },
    "carriers_launched": 0,
    "carriers_total": 1
  },
  "meta": { "request_id": "req_01k2setupd", "timestamp": "2026-10-01T10:00:00.000Z" }
}

Watch the transition on the same read: when the carriers accept, verification_status moves to verified; after POST /api/v1/rcs/bots/:id/launch, carrier_statuses."310260".status flips to launched and carriers_launched reaches 1 — the bot is sendable from that point.

5. After the submit

Verification starts the moment the setup posts:

The agent goes straight into carrier review. There is no Devotel-side approval wait for RCS — the aggregator and the carriers review the brand and the agent together from the single submission. Watch the verdict on Messages → RCS → Bots or by polling GET /api/v1/rcs/bots/:id/quality for verification_status.
Complete verification the same way as the split flow. Screenshots and KYC documents go through POST /api/v1/rcs/bots/:id/verify; the walk-through is in the RCS onboarding guide and the verification/KYC guide.
Launch per carrier once verified. POST /api/v1/rcs/bots/:id/launch asks the carriers to take the agent live; the bot is sendable when carrier_statuses shows launched on at least one carrier.
Add later agents to the same brand. Use Settings → Channels → RCS or POST /api/v1/rcs/bots — the setup wizard stays closed once any brand exists.

Troubleshooting

Symptom	Cause and fix
Submit stays disabled	A required field is blank, or both agent contact fields are empty — the form needs at least one of phone or email for the agent.
`422 BRAND_ALREADY_EXISTS`	The workspace already has a brand — create the next agent on it via `POST /api/v1/rcs/bots` (or Settings → Channels → RCS), not this page.
”Unknown carrier mccmnc”	One carrier code is not in the aggregator’s directory — recheck the code against mcc-mnc.com and resubmit.

RCS onboarding — the full API path from brand to launch, plus verification, per-carrier launch, and reach sizing.
RCS brands console — the granular Messages → RCS → Brands surface for later brands and agents.
RCS channel page — message shapes, rich cards, and channel behavior.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

RCS setup wizard: brand and first agent in one form

RCS Setup Wizard: Brand and First Agent in One Form

1. Where the wizard lives

2. One-shot wizard vs the split flow

3. The form, card by card

Brand identity

Contact person

Company address

First agent

4. What the submission does

5. After the submit

Troubleshooting

​RCS Setup Wizard: Brand and First Agent in One Form

​1. Where the wizard lives

​2. One-shot wizard vs the split flow

​3. The form, card by card

​Brand identity

​Contact person

​Company address

​First agent

​4. What the submission does

​5. After the submit

​Troubleshooting

​Related

RCS Setup Wizard: Brand and First Agent in One Form

1. Where the wizard lives

2. One-shot wizard vs the split flow

3. The form, card by card

Brand identity

Contact person

Company address

First agent

4. What the submission does

5. After the submit

Troubleshooting

Related