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)	Also used as the first agent’s logo — the aggregator rejects an agent without one. Aim for 400×400 PNG/JPG under ~90KB; size is a recommendation, not a rejection.
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

Required for KYC-mandatory countries (India, Brazil, and others): address line 1, city, country, and postal code are required; address line 2 and state/province are optional. 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 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"
  }'

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

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