---
title: "Update Test Agent"
method: PATCH
path: "/rcs/test/agents/{agentId}"
tags: ["rcs > test"]
---

# Update Test Agent

`PATCH /rcs/test/agents/{agentId}`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/rcs/test/agents/{agentId}`
- Auth: API key in header `PINNACLE-API-KEY`

Update an existing RCS test agent's configuration.

All fields are optional — only include the fields you want to update.

## Image Requirements

If updating images, the same requirements apply as when creating an agent:

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

> **2-Minute Cooldown**
>
> After updating 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.

## Path parameters

- `agentId` string, required

## Request body

- UpdateTestAgentRequest: Request body for updating an existing RCS test agent. All fields are optional — only include the fields you want to update. At least one field must be provided.
  - `displayName` string: Display name of the agent shown to users in RCS conversations. Must be between 1 and 40 characters.
  - `description` string: Short description of what the agent does. Must be between 1 and 100 characters.
  - `logoUrl` string, uri: URL to the agent's logo image. **Requirements:** - Format: JPEG or PNG - Max file size: 50 KB - Recommended: Square aspect ratio
  - `heroUrl` string, uri: URL to the agent's hero banner image. **Requirements:** - Format: JPEG or PNG - Max file size: 200 KB - Recommended: Landscape aspect ratio
  - `phoneNumbers` AgentPhoneEntry[]: Contact phone numbers displayed on the agent's profile. At least 1 and up to 3 entries.
    - `number` string, required: Phone number in E.164 format (e.g., `+14155550123`).
    - `label` string, required: Display label for the phone number (e.g., "Support", "Sales").
  - `emails` AgentEmailEntry[]: Contact email addresses displayed on the agent's profile. At least 1 and up to 3 entries.
    - `address` string, email, required: A valid email address.
    - `label` string, required: Display label for the email (e.g., "Support", "Sales").
  - `websites` AgentWebsiteEntry[]: Website links displayed on the agent's profile. At least 1 and up to 3 entries.
    - `url` string, uri, required: A valid URL for the website.
    - `label` string, required: Display label for the website (e.g., "Website", "Help Center").
  - `privacyUrl` string, uri: URL to the agent's privacy policy.
  - `termsUrl` string, uri: URL to the agent's terms and conditions.
  - `color` string: The agent's brand color as a hex color code. Must have sufficient contrast with white.
  - `isConversational` boolean: Whether the agent supports two-way conversations.
  - `agentUseCase` 'TRANSACTIONAL' | 'PROMOTIONAL' | 'OTP' | 'MULTI_USE': 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.

## Response `200`

The test agent was updated successfully.

- TestAgentResponse: Response returned after creating or updating a test agent.
  - `id` string, required: The unique agent ID. Use this ID when sending messages, whitelisting numbers, and performing other agent operations. Always prefixed with `agent_`.
  - `type` 'TEST', required: The type of the agent. Test agents always have type `TEST`.
  - `serviceId` string, required: The RCS service ID assigned to this agent by the carrier network. Used internally for routing messages. You can use this to construct RCS deep links manually.
  - `details` RcsAgentDetails, required: The configuration details of an RCS agent, as returned by the GET endpoint.
    - `name` string: Display name of the agent.
    - `description` string: Description of the agent.
    - `iconUrl` string, uri, nullable: URL to the agent's logo image.
    - `heroUrl` string, uri, nullable: URL to the agent's hero banner image.
    - `color` string: The agent's brand color hex code.
    - `phones` RcsAgentDetailsPhonesItems[]: Contact phone numbers for the agent.
      - `phone` string: Phone number in E.164 format.
      - `label` string: Display label for the phone number.
    - `emails` RcsAgentDetailsEmailsItems[]: Contact email addresses for the agent.
      - `email` string: Email address.
      - `label` string: Display label for the email.
    - `websites` RcsAgentDetailsWebsitesItems[]: Website links for the agent.
      - `url` string: Website URL.
      - `label` string: Display label for the website.
    - `privacyUrl` string, uri, nullable: URL to the agent's privacy policy.
    - `termsUrl` string, uri, nullable: URL to the agent's terms and conditions.
    - `isConversational` boolean, nullable: Whether the agent supports two-way conversations. `true` for agents that respond to user messages, `false` for send-only agents (e.g., notifications).
    - `agentUseCase` 'TRANSACTIONAL' | 'PROMOTIONAL' | 'OTP' | 'MULTI_USE': The primary use case for the RCS agent. - `TRANSACTIONAL` — Order confirmations, shipping updates, appointment reminders. - `PROMOTIONAL` — Marketing messages, offers, discounts. - `OTP` — One-time passwords and verification codes. - `MULTI_USE` — A combination of transactional, promotional, and/or OTP messaging.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The test agent was not found. This can occur if: - The agent ID does not exist. - The agent does not belong to your account. - The associated brand was not found. Contact founders@pinnacle.sh to resolve this issue.
- `500`: An internal error occurred. Common causes: - **Invalid image:** Logo exceeds 50 KB, hero exceeds 200 KB, or image is not JPEG/PNG. - **Invalid color:** The hex color does not have sufficient contrast with white.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)