The Test Agent is a shared, pre-approved RCS agent. You whitelist your phone number, then send up to five real RCS messages for integration testing — without completing full production agent approval first.
You can only send test traffic to your verified phone number. The API returns a generic 403 if the target number is not yours — this protects other accounts’ numbers from enumeration.

​
Prerequisites

  • An API key from the dashboard (Authorization: Bearer …).
  • A device that supports RCS on the registered number.
  • curl or any HTTP client (examples below use curl).

​
Steps

1

Create an API key

In the dashboard, create a Developer API key and store it in a secret:
export CPAAS_API_KEY=your_api_key_here
Keys are scoped to your workspace and rate-limited per key.
2

Register your phone

Call POST /v1/test/register with your phone number. The platform sends an OTP to that device via SMS.
curl -sS -X POST "https://api.arowana.app/v1/test/register" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+4917612345678"}'
3

Verify the OTP

Call POST /v1/test/verify with the code from SMS. This claims a slot in the Test Agent pool and binds the number to your workspace.
curl -sS -X POST "https://api.arowana.app/v1/test/verify" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+4917612345678", "code": "123456"}'
4

Send a test RCS message

Call POST /v1/test/messages with the same JSON body structure as POST /v1/messages — text, rich card, or carousel all work.
curl -sS -X POST "https://api.arowana.app/v1/test/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+4917612345678",
    "agent_id": "ag_test_xxxx",
    "content": { "text": "Hello from the sandbox!" },
    "traffic_type": "TRANSACTION"
  }'
You can send at most five messages on this path. Use them to test different content shapes.
5

Check quota and delivery status

GET /v1/test/status shows remaining quota and assignment details. GET /v1/messages/{id} shows the delivery timeline once you have a message_id.
curl -sS "https://api.arowana.app/v1/test/status" \
  -H "Authorization: Bearer $API_KEY"

​
Base URL

Replace https://api.arowana.app with the hostname your workspace provides. The same host serves /v1 for production sends and /v1/test/* for the sandbox.

​
Troubleshooting

The most common causes are:
  • The to number in your request does not match the number you registered and verified.
  • Your API key does not have send permission, or belongs to a different workspace.
  • The OTP verification step was not completed successfully — call GET /v1/test/status to check your slot state.
RCS requires Android with RCS enabled and a supported carrier. Verify that RCS is active in your messaging app settings. If the device shows SMS instead of RCS, the network may have downgraded the delivery — this is a device/carrier issue, not a platform error.
The five-message limit is per verified number and is not resettable. If you need to test more content shapes, consider moving to a production agent — see RCS agents for the approval flow.

​
Next steps

Messages API

Full POST / GET / DELETE message reference and payload examples.

RCS endpoints

Production agents, messaging, delivery tracking, and Test Agent routes.

Introduction to RCS

Traffic types, agents, and production vs test explained.

Webhooks

Subscribe to delivery, read, and agent events with HMAC verification.