Create Test Agent API Reference

Serverhttps://api.pinnacle.sh/

Create a new RCS test agent for development and testing.

Overview

Test agents let you build and test full RCS functionality — rich cards, carousels, buttons, quick replies, and media messages — without going through the full carrier review process. Messages from test agents can only be sent to whitelisted phone numbers.

Limits

Maximum 5 test agents per account.

Image Requirements

Image	Format	Max Size
Logo	JPEG, PNG	50 KB
Hero	JPEG, PNG	200 KB

After Creation

Once your test agent is created, you'll need to:

Whitelist test phone numbers using POST /rcs/test/agents/{agentId}/whitelist.
Accept the tester invite on each whitelisted device.
Send messages using POST /messages/send/rcs with the returned agent ID as the from field.

2-Minute Cooldown

After creating a test agent, there is a mandatory 2-minute cooldown before you can whitelist phone numbers. This is a requirement imposed by Google's RBM platform.

Authorization

Pinnacle API key

PINNACLE-API-KEY<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for creating a new RCS test agent.

Test agents allow you to develop and test RCS functionality before going through carrier review. Each account can create up to 5 test agents.

displayNamestring

Display name of the agent shown to users in RCS conversations. Must be between 1 and 40 characters.

Length

1 <= length <= 40

Example

"Acme Support"

descriptionstring

Short description of what the agent does. Shown to users in the agent's profile. Must be between 1 and 100 characters.

Length

1 <= length <= 100

Example

"Get help with your Acme orders and account"

logoUrlstring

URL to the agent's logo image. Displayed as the agent's avatar in conversations.

Requirements:

Format: JPEG or PNG
Max file size: 50 KB
Recommended: Square aspect ratio

Format

uri

Example

"https://example.com/logo.png"

heroUrlstring

URL to the agent's hero banner image. Displayed at the top of the agent's profile.

Requirements:

Format: JPEG or PNG
Max file size: 200 KB
Recommended: Landscape aspect ratio

Format

uri

Example

"https://example.com/hero.png"

array<object>

Contact phone numbers displayed on the agent's profile. At least 1 and up to 3 entries.

Items

1 <= items <= 3

array<object>

Contact email addresses displayed on the agent's profile. At least 1 and up to 3 entries.

Items

1 <= items <= 3

array<object>

Website links displayed on the agent's profile. At least 1 and up to 3 entries.

Items

1 <= items <= 3

privacyUrlstring

URL to the agent's privacy policy.

Format

uri

Example

"https://example.com/privacy"

termsUrlstring

URL to the agent's terms and conditions.

Format

uri

Example

"https://example.com/terms"

colorstring

The agent's brand color as a hex color code. Used for UI accents in the RCS conversation. Must have sufficient contrast with white for accessibility.

Match

^#([0-9A-Fa-f]{6})$

Example

"#FF6B00"

isConversationalboolean

Whether the agent supports two-way conversations. Set to true if the agent will respond to user messages. Set to false for send-only agents (e.g., notifications).

Example

true

agentUseCasestringOptional

The primary use case for the RCS agent. This helps carriers understand the purpose of the agent during review.

TRANSACTIONAL — Order confirmations, shipping updates, appointment reminders, and similar transactional notifications.
PROMOTIONAL — Marketing messages, offers, discounts, and promotional content.
OTP — One-time passwords and verification codes.
MULTI_USE — A combination of transactional, promotional, and/or OTP messaging.

Allowed values

"TRANSACTIONAL""PROMOTIONAL""OTP""MULTI_USE"

Response Body

`application/json`

Pinnacle client libraries

import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.rcs.test.createAgent({
    displayName: "Acme Support",
    description: "Get help with your Acme orders and account",
    logoUrl: "https://example.com/logo.png",
    heroUrl: "https://example.com/hero.png",
    phoneNumbers: [{
            number: "+14155550123",
            label: "Support"
        }],
    emails: [{
            address: "support@example.com",
            label: "Support"
        }],
    websites: [{
            url: "https://example.com",
            label: "Website"
        }],
    privacyUrl: "https://example.com/privacy",
    termsUrl: "https://example.com/terms",
    color: "#FF6B00",
    isConversational: true,
    agentUseCase: "MULTI_USE"
});

Responses

{  "id": "agent_abc123def456",  "type": "TEST",  "serviceId": "acme-support_agent",  "details": {    "name": "Acme Support",    "description": "Get help with your Acme orders and account",    "iconUrl": "https://example.com/logo.png",    "heroUrl": "https://example.com/hero.png",    "color": "#FF6B00",    "phones": [      {        "phone": "+14155550123",        "label": "Support"      }    ],    "emails": [      {        "email": "support@example.com",        "label": "Support"      }    ],    "websites": [      {        "url": "https://example.com",        "label": "Website"      }    ],    "privacyUrl": "https://example.com/privacy",    "termsUrl": "https://example.com/terms",    "isConversational": true,    "agentUseCase": "MULTI_USE"  }}

Create Test Agent

Overview

Limits

Image Requirements

After Creation

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

403application/json

500application/json

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`