> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/rcs-agents/test/update-agent/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Update Test Agent

PATCH https://api.pinnacle.sh/rcs/test/agents/{agentId}
Content-Type: application/json

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.


Reference: https://docs.pinnacle.sh/api-reference/rcs-agents/test/update-agent

## Authentication

- `PINNACLE-API-KEY` header (required) — API Key authentication via header

## Request

### Path parameters

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

### Body (application/json)

This endpoint expects an UpdateTestAgentRequest.

- `displayName` (string, optional) — Display name of the agent shown to users in RCS conversations. Must be between 1 and 40 characters.
- `description` (string, optional) — Short description of what the agent does. Must be between 1 and 100 characters.
- `logoUrl` (string, optional) — URL to the agent's logo image. **Requirements:** - Format: JPEG or PNG - Max file size: 50 KB - Recommended: Square aspect ratio
- `heroUrl` (string, optional) — URL to the agent's hero banner image. **Requirements:** - Format: JPEG or PNG - Max file size: 200 KB - Recommended: Landscape aspect ratio
- `phoneNumbers` (list of AgentPhoneEntry, optional) — Contact phone numbers displayed on the agent's profile. At least 1 and up to 3 entries.
- `emails` (list of AgentEmailEntry, optional) — Contact email addresses displayed on the agent's profile. At least 1 and up to 3 entries.
- `websites` (list of AgentWebsiteEntry, optional) — Website links displayed on the agent's profile. At least 1 and up to 3 entries.
- `privacyUrl` (string, optional) — URL to the agent's privacy policy.
- `termsUrl` (string, optional) — 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` (enum, optional) — 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

### 200

The test agent was updated successfully.

- `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` (enum, required) — The type of the agent. Test agents always have type `TEST`.
  - Allowed values: `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.

## Errors

### 400 Bad Request Error

Validation failed. The payload has missing required fields and/or invalid types.  See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information.

- `description` (string, required) — Human-readable summary of validation failures.
- `errors` (ZodErrorErrors, required) — 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

### 401 Unauthorized Error

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.

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

### 403 Forbidden Error

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.

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

### 404 Not Found Error

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.

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

### 500 Internal Server Error

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.

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

## Types

### AgentPhoneEntry

A phone number contact entry for the RCS agent's contact information.

- `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").

### AgentEmailEntry

An email contact entry for the RCS agent's contact information.

- `address` (string, required) — A valid email address.
- `label` (string, required) — Display label for the email (e.g., "Support", "Sales").

### AgentWebsiteEntry

A website contact entry for the RCS agent's contact information.

- `url` (string, required) — A valid URL for the website.
- `label` (string, required) — Display label for the website (e.g., "Website", "Help Center").

### RcsAgentDetails

The configuration details of an RCS agent, as returned by the GET endpoint.

- `name` (string, optional) — Display name of the agent.
- `description` (string, optional) — Description of the agent.
- `iconUrl` (string, optional, nullable) — URL to the agent's logo image.
- `heroUrl` (string, optional, nullable) — URL to the agent's hero banner image.
- `color` (string, optional) — The agent's brand color hex code.
- `phones` (list of RcsAgentDetailsPhonesItems, optional) — Contact phone numbers for the agent.
- `emails` (list of RcsAgentDetailsEmailsItems, optional) — Contact email addresses for the agent.
- `websites` (list of RcsAgentDetailsWebsitesItems, optional) — Website links for the agent.
- `privacyUrl` (string, optional, nullable) — URL to the agent's privacy policy.
- `termsUrl` (string, optional, nullable) — URL to the agent's terms and conditions.
- `isConversational` (boolean, optional, 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` (enum, optional, nullable) — 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.
  - Allowed values: `TRANSACTIONAL`, `PROMOTIONAL`, `OTP`, `MULTI_USE`

### ZodErrorErrors

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

### RcsAgentDetailsPhonesItems

- `phone` (string, optional) — Phone number in E.164 format.
- `label` (string, optional) — Display label for the phone number.

### RcsAgentDetailsEmailsItems

- `email` (string, optional) — Email address.
- `label` (string, optional) — Display label for the email.

### RcsAgentDetailsWebsitesItems

- `url` (string, optional) — Website URL.
- `label` (string, optional) — Display label for the website.

## Examples

### Updated Test Agent

**Response**

```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"
  }
}
```

**SDK Code**

```python Updated Test Agent
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

headers = {"PINNACLE-API-KEY": "<apiKey>"}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Updated Test Agent
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456';
const options = {method: 'PATCH', headers: {'PINNACLE-API-KEY': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Updated Test Agent
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Updated Test Agent
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Updated Test Agent
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .asString();
```

```php Updated Test Agent
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456', [
  'headers' => [
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Updated Test Agent
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456");
var request = new RestRequest(Method.PATCH);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Updated Test Agent
import Foundation

let headers = ["PINNACLE-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Update Display Name

**Request**

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

**Response**

```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"
  }
}
```

**SDK Code**

```python Update Display Name
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

payload = { "displayName": "Acme Premium Support" }
headers = {
    "PINNACLE-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Update Display Name
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456';
const options = {
  method: 'PATCH',
  headers: {'PINNACLE-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"displayName":"Acme Premium Support"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Update Display Name
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

	payload := strings.NewReader("{\n  \"displayName\": \"Acme Premium Support\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Update Display Name
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"displayName\": \"Acme Premium Support\"\n}"

response = http.request(request)
puts response.read_body
```

```java Update Display Name
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"displayName\": \"Acme Premium Support\"\n}")
  .asString();
```

```php Update Display Name
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456', [
  'body' => '{
  "displayName": "Acme Premium Support"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Update Display Name
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456");
var request = new RestRequest(Method.PATCH);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"displayName\": \"Acme Premium Support\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Update Display Name
import Foundation

let headers = [
  "PINNACLE-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["displayName": "Acme Premium Support"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Update Multiple Fields

**Request**

```json
{
  "displayName": "Acme Premium Support",
  "description": "Premium support for Acme customers",
  "color": "#0066FF"
}
```

**Response**

```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"
  }
}
```

**SDK Code**

```python Update Multiple Fields
import requests

url = "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

payload = {
    "displayName": "Acme Premium Support",
    "description": "Premium support for Acme customers",
    "color": "#0066FF"
}
headers = {
    "PINNACLE-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Update Multiple Fields
const url = 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456';
const options = {
  method: 'PATCH',
  headers: {'PINNACLE-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"displayName":"Acme Premium Support","description":"Premium support for Acme customers","color":"#0066FF"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Update Multiple Fields
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456"

	payload := strings.NewReader("{\n  \"displayName\": \"Acme Premium Support\",\n  \"description\": \"Premium support for Acme customers\",\n  \"color\": \"#0066FF\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Update Multiple Fields
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"displayName\": \"Acme Premium Support\",\n  \"description\": \"Premium support for Acme customers\",\n  \"color\": \"#0066FF\"\n}"

response = http.request(request)
puts response.read_body
```

```java Update Multiple Fields
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"displayName\": \"Acme Premium Support\",\n  \"description\": \"Premium support for Acme customers\",\n  \"color\": \"#0066FF\"\n}")
  .asString();
```

```php Update Multiple Fields
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456', [
  'body' => '{
  "displayName": "Acme Premium Support",
  "description": "Premium support for Acme customers",
  "color": "#0066FF"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Update Multiple Fields
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456");
var request = new RestRequest(Method.PATCH);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"displayName\": \"Acme Premium Support\",\n  \"description\": \"Premium support for Acme customers\",\n  \"color\": \"#0066FF\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Update Multiple Fields
import Foundation

let headers = [
  "PINNACLE-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "displayName": "Acme Premium Support",
  "description": "Premium support for Acme customers",
  "color": "#0066FF"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/test/agents/agent_abc123def456")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.