> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Register an RCS Agent

> Register an RCS brand and agent, test the agent, and submit it for carrier launch through the Telnyx API.

# 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:

```bash theme={null}
export TELNYX_API_KEY="YOUR_API_KEY"
```

<Note>
  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.
</Note>

## Stage 1: Create and test the agent

### Create a brand

A brand represents the legal business operating the RCS agent.

```bash theme={null}
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

```bash theme={null}
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`:

```bash theme={null}
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.

```bash theme={null}
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`.

<Warning>
  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.
</Warning>

### Submit the agent basics

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
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](/docs/messaging/messages/send-an-rcs-message/index).