# Update Test Agent

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

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.

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Parameters

- `agentId` — path, string. The RCS agent ID (must be prefixed with `agent_`).

## Request body

Required.

Content type: `application/json`.

### Fields

- `displayName` — `string`, optional, minimum length: 1; maximum length: 40. Display name of the agent shown to users in RCS conversations.
Must be between 1 and 40 characters.
- `description` — `string`, optional, minimum length: 1; maximum length: 100. Short description of what the agent does.
Must be between 1 and 100 characters.
- `logoUrl` — `string`, optional, format: uri. URL to the agent's logo image.

**Requirements:**
- Format: JPEG or PNG
- Max file size: 50 KB
- Recommended: Square aspect ratio
- `heroUrl` — `string`, optional, format: 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[]`, optional. Contact phone numbers displayed on the agent's profile. At least 1 and up to 3 entries.
- `phoneNumbers[].number` — `string`. Phone number in E.164 format (e.g., `+14155550123`).
- `phoneNumbers[].label` — `string`, minimum length: 1; maximum length: 100. Display label for the phone number (e.g., "Support", "Sales").
- `emails` — `AgentEmailEntry[]`, optional. Contact email addresses displayed on the agent's profile. At least 1 and up to 3 entries.
- `emails[].address` — `string`, format: email. A valid email address.
- `emails[].label` — `string`, minimum length: 1; maximum length: 100. Display label for the email (e.g., "Support", "Sales").
- `websites` — `AgentWebsiteEntry[]`, optional. Website links displayed on the agent's profile. At least 1 and up to 3 entries.
- `websites[].url` — `string`, format: uri. A valid URL for the website.
- `websites[].label` — `string`, minimum length: 1; maximum length: 100. Display label for the website (e.g., "Website", "Help Center").
- `privacyUrl` — `string`, optional, format: uri. URL to the agent's privacy policy.
- `termsUrl` — `string`, optional, format: uri. URL to the agent's terms and conditions.
- `color` — `string`, optional. The agent's brand color as a hex color code. Must have sufficient contrast with white.
- `isConversational` — `boolean`, optional. Whether the agent supports two-way conversations.
- `agentUseCase` — `AgentUseCase`, optional, values: `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.

### Example

```json
{
  "displayName": "Acme Premium Support"
}
```

## Responses

### 200

The test agent was updated successfully.

Content type: `application/json`. Schema: `TestAgentResponse`.

- `id` — `string`. The unique agent ID. Use this ID when sending messages, whitelisting numbers,
and performing other agent operations. Always prefixed with `agent_`.
- `type` — `string`, values: `TEST`. The type of the agent. Test agents always have type `TEST`.
- `serviceId` — `string`. 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`. The configuration details of an RCS agent, as returned by the GET endpoint.
- `details.name` — `string`, optional. Display name of the agent.
- `details.description` — `string`, optional. Description of the agent.
- `details.iconUrl` — `string`, optional, format: uri. URL to the agent's logo image.
- `details.heroUrl` — `string`, optional, format: uri. URL to the agent's hero banner image.
- `details.color` — `string`, optional. The agent's brand color hex code.
- `details.phones` — `object[]`, optional. Contact phone numbers for the agent.
- `details.phones[].phone` — `string`, optional. Phone number in E.164 format.
- `details.phones[].label` — `string`, optional. Display label for the phone number.
- `details.emails` — `object[]`, optional. Contact email addresses for the agent.
- `details.emails[].email` — `string`, optional. Email address.
- `details.emails[].label` — `string`, optional. Display label for the email.
- `details.websites` — `object[]`, optional. Website links for the agent.
- `details.websites[].url` — `string`, optional. Website URL.
- `details.websites[].label` — `string`, optional. Display label for the website.
- `details.privacyUrl` — `string`, optional, format: uri. URL to the agent's privacy policy.
- `details.termsUrl` — `string`, optional, format: uri. URL to the agent's terms and conditions.
- `details.isConversational` — `boolean`, optional. Whether the agent supports two-way conversations. `true` for agents that respond
to user messages, `false` for send-only agents (e.g., notifications).
- `details.agentUseCase` — `string`, optional, values: `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.

Example:

```json
{
  "id": "agent_abc123def456",
  "type": "TEST",
  "serviceId": "acme-support_agent",
  "details": {
    "name": "Acme Premium Support",
    "description": "Premium support for Acme customers",
    "iconUrl": "https://example.com/logo.png",
    "heroUrl": "https://example.com/hero.png",
    "color": "#0066FF",
    "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"
  }
}
```

### 400

Validation failed. The payload has missing required fields and/or invalid types.

See https://zod.dev/error-formatting for more information.

Content type: `application/json`. Schema: `object`.

- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [
      "Unrecognized key: 'extraKey'"
    ],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Your subscription does not include access to 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.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Test agent not found"
}
```

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

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

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

await client.rcs.test.updateAgent("agent_abc123def456", {
    displayName: "Acme Premium Support"
});
```

### Python

```python
import os
from rcs import Pinnacle

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.rcs.test.update_agent(
    agent_id="agent_abc123def456",
    display_name="Acme Premium Support",
    description="Premium support for Acme customers",
    color="#0066FF",
)
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.rcs.test.update_agent(
  agent_id: "agent_abc123def456",
  display_name: "Acme Premium Support"
)
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)