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, submits its basic configuration, and adds test devices. The second stage provides 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:

export TELNYX_API_KEY="YOUR_API_KEY"

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.

curl -X POST "https://api.telnyx.com/v2/rcs/brands" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme",
    "legal_name": "Acme LLC",
    "legal_entity_type": "LIMITED_LIABILITY_COMPANY",
    "organization_type": "PRIVATE_PROFIT",
    "website_url": "https://www.example.com",
    "profile_id": "40000000-0000-0000-0000-000000000001",
    "identifiers": {
      "ein": {
        "identifier_type": "EIN",
        "value": "12-3456789"
      }
    },
    "addresses": {
      "primary": {
        "line_1": "1 Main Street",
        "city": "Chicago",
        "administrative_area": "IL",
        "postal_code": "60601",
        "country_code": "US"
      }
    },
    "contacts": {
      "brand": {
        "contact_type": "BRAND",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": "Messaging Operations Manager",
        "email": "jane@example.com",
        "phone_number": "+13125550100"
      }
    }
  }'

Save the returned brand_id. A brand can be updated while its status is CREATED. After submission, its registration fields are locked.

Submit the brand

curl -X POST "https://api.telnyx.com/v2/rcs/brands/BRAND_ID/submit" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

The endpoint returns 202 Accepted. Poll the brand until its status becomes VERIFIED:

curl "https://api.telnyx.com/v2/rcs/brands/BRAND_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

Do not submit an agent until the brand is VERIFIED. REJECTED and FAILED are terminal states that require investigation before creating another registration.

Create the agent basics

Create the agent with only the information needed for the first stage. The Idempotency-Key is required. Reuse the same key and request body when retrying an uncertain response.

curl -X POST "https://api.telnyx.com/v2/rcs/agents" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-order-updates-v1" \
  -d '{
    "brand_id": "BRAND_ID",
    "display_name": "Acme Order Updates",
    "use_case": "TRANSACTIONAL",
    "configuration": {
      "basics": {
        "description": "Order confirmations and delivery updates",
        "logo_url": "https://www.example.com/rcs/logo.png",
        "hero_url": "https://www.example.com/rcs/hero.png",
        "brand_color": "#123456",
        "privacy_policy_url": "https://www.example.com/privacy",
        "terms_and_conditions_url": "https://www.example.com/terms",
        "email": {
          "address": "support@example.com",
          "label": "Support"
        }
      }
    }
  }'

Save the returned agent_id. Agent fields can be updated while the status is CREATED.

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.

Submit the agent basics

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/submit" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

This starts provider provisioning and basic agent review. Follow progress with:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

When basics_status is SUBMITTED or APPROVED, the agent can remain in this stage during testing and while carrier launch information is gathered. There is no requirement to begin the second stage immediately.

Add a test device

After the basic submission completes, add an RCS-capable phone number in E.164 format:

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/test_devices" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+13125550123"
  }'

List the agent’s test devices:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/test_devices" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

Stage 2: Submit the agent for launch

Start this stage after gathering the campaign, consent, and testing information needed for carrier review. 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.

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/launch" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
      "company_overview": "Acme provides online retail services.",
      "agent_overview": "The agent sends order confirmations and delivery updates.",
      "interactions": [
        {
          "interaction_type": "TRANSACTIONAL_UPDATES"
        },
        {
          "interaction_type": "CUSTOMER_SUPPORT"
        }
      ],
      "message_examples": [
        "Your Acme order is confirmed.",
        "Your Acme order has shipped.",
        "Your Acme order was delivered."
      ],
      "consent_settings": {
        "opt_in_methods": [
          {
            "method_type": "WEBSITE"
          }
        ],
        "call_to_action": "Select RCS updates during checkout.",
        "call_to_action_url": "https://www.example.com/checkout",
        "call_to_action_media_url": "https://www.example.com/rcs/opt-in.png",
        "double_opt_in": false,
        "opt_in_message": "You are subscribed to Acme order updates.",
        "help_response": "Contact support@example.com for help.",
        "opt_out_response": "You will receive no more messages."
      }
    },
    "testing": {
      "test_url": "https://www.example.com/rcs/test-video",
      "additional_information": "The video demonstrates START, STOP, HELP, and an order-status interaction."
    }
  }'

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:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

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.

Agent status	Meaning
`CREATED`	The agent is an editable draft.
`SUBMITTED`	Telnyx has started the provider submission.
`VERIFYING`	External verification is in progress.
`VERIFIED`	Verification completed and launch can proceed.
`LAUNCHING`	Carrier launch is in progress.
`LAUNCHED`	Launch completed and activation is being finalized.
`LIVE`	The agent is active for RCS messaging.
`REJECTED`	External review rejected the agent.
`FAILED`	Processing stopped after a terminal failure.

Once the agent is LIVE, continue with Send an RCS message.

Getting Started

RCS Brands API

RCS Agents API

Sending Messages

Receiving Messages

RCS API

For AI Agents

Quickstart: Register an RCS Agent

Register an RCS agent

Prerequisites

Stage 1: Create and test the agent

Create a brand

Submit the brand

Create the agent basics

Submit the agent basics

Add a test device

Stage 2: Submit the agent for launch

Monitor launch status

​Register an RCS agent

​Prerequisites

​Stage 1: Create and test the agent

​Create a brand

​Submit the brand

​Create the agent basics

​Submit the agent basics

​Add a test device

​Stage 2: Submit the agent for launch

​Monitor launch status

Register an RCS agent

Prerequisites

Stage 1: Create and test the agent

Create a brand

Submit the brand

Create the agent basics

Submit the agent basics

Add a test device

Stage 2: Submit the agent for launch

Monitor launch status