Skip to main content

Register an RCS agent

This quickstart takes an RCS agent from brand registration to carrier launch. The process has two stages, allowing the agent to be created and tested before all carrier launch information is available. The first stage registers the brand, creates the agent, and adds test devices. No agent submission is needed to test. The second stage submits the agent’s basic configuration, then the campaign and testing evidence needed for carrier review.

Prerequisites

Before starting, gather:
  • A Telnyx account with an API key
  • A Messaging Profile ID
  • Business registration details, including the legal name, EIN, address, website, and contact
  • Public HTTPS URLs for the agent logo, hero image, privacy policy, and terms and conditions
Set the API key as an environment variable:
RCS registration is asynchronous. A successful submission means Telnyx accepted the work, not that external review is complete. Use the retrieve endpoints to follow each resource’s status.

Stage 1: Create and test the agent

Create a brand

A brand represents the legal business operating the RCS agent.
Save the returned brand_id. A brand can be updated while its status is CREATED. After submission, its registration fields are locked unless the brand becomes REJECTED or FAILED.

Submit the brand

The endpoint returns 202 Accepted. Telnyx creates the brand with the provider and starts the external brand review. Submitting the brand does not charge a fee. Submitting the brand is not required to create an agent, but it is required before test devices can be added, because test devices need the agent to exist with the provider. To test an agent before submitting it, wait until the brand status is no longer CREATED before creating the agent. Follow the brand status with:
A REJECTED or FAILED brand cannot accept new agents or agent submissions. Correct the brand with PATCH /v2/rcs/brands/BRAND_ID. The update must change at least one field. It clears the failure reason and returns the brand to CREATED. Then submit the brand again.

Create the agent

Create the agent with only the information needed for the first stage. The brand does not need to be submitted first, but it cannot be REJECTED or FAILED. The Idempotency-Key is required. Reuse the same key and request body when retrying an uncertain response.
Save the returned agent_id. Agent fields can be updated while the status is CREATED, unless Telnyx is still creating the agent with the provider or a test device invitation is PENDING. When the brand status is no longer CREATED, Telnyx also creates the agent with the provider in the background. The agent stays CREATED and is not submitted for review. If the provider cannot create the agent, its status becomes FAILED or REJECTED. An agent created while its brand is still CREATED might not be created with the provider until its basics are submitted, so test devices cannot be added to it before then.
Using an existing idempotency key with a different request returns a conflict. Do not generate a new key for a retry of the same logical agent creation.

Add a test device

Test devices can be added without submitting the agent basics. Add an RCS-capable phone number in E.164 format:
List the agent’s test devices:
A 409 Conflict means the agent does not exist with the provider yet. Wait and retry. If it persists, retrieve the agent and check its status, and check that the brand status was no longer CREATED when the agent was created. Each test device has an invite_status of PENDING, ACCEPTED, or DECLINED. While any invitation is PENDING, the agent cannot be updated and its basics cannot be submitted; those requests return 409. Wait until every invitation is accepted or declined, or remove the pending test devices, then wait briefly and retry. The agent can stay in this stage during testing and while carrier launch information is gathered. There is no requirement to begin the second stage immediately.

Stage 2: Submit the agent for launch

Start this stage when ready to move forward with carrier launch.

Submit the agent basics

The brand must be submitted (status SUBMITTED, REVIEWING, VETTING, or VERIFIED) before the agent basics can be submitted.
The agent’s logo and hero image are fetched and checked again on submission. Submitting the agent basics charges a one-time vetting fee for the agent. If the account has insufficient funds, the request returns 402 with the code billing_insufficient_funds. Add funds and submit again. A repeated submission does not charge the fee again. If the agent is still being created with the provider, or a test device invitation is still PENDING, the request returns 409. Wait and retry. The endpoint returns 202 Accepted and starts the basic agent review. Follow progress with:
Continue when basics_status is SUBMITTED or APPROVED.

Submit the campaign and testing information

Submit the campaign, consent, and testing information needed for carrier review. Submitting for launch charges the one-time launch fee and starts the monthly agent fee. Insufficient funds return the same 402 as the basics submission. Carrier rejection or a technical failure does not refund these charges automatically; contact support for billing adjustments. The testing.test_url must point to a publicly accessible video that demonstrates START, STOP, and HELP behavior and an example interaction with the agent.
The endpoint returns 202 Accepted. Telnyx submits the campaign and testing sections in the order required by the provider, then tracks external review and launch.

Monitor launch status

Retrieve the agent until status becomes LIVE:
The agent response includes section statuses, test devices, carrier approvals, and provider capabilities. Carrier approval may be reported as an aggregate hub status when the provider does not expose individual carrier results. Once the agent is LIVE, continue with Send an RCS message.