Sign in

v2

latestOpenAPI 3.1.02026-08-07750280.6 KB
Agents

Update agent conversation copy

Update the conversation copy of a specific agent.

Updatable fields (partial update — only the fields you send are changed):
- `prompt_instructions`: the custom instructions driving the agent behaviour
- `first_message`: the message the agent says when the conversation starts

Sending an explicit `null` (or a blank string) clears the field, so the
agent falls back to its default behaviour. Omitting a field leaves it
untouched. An empty body is rejected with 400.

Call-routing configuration (voice, AI provider, phone numbers, agent type)
is intentionally NOT updatable from the External API: changing it can break
live calls. Use the dashboard for those fields.

Unknown fields are rejected with 400, so a typo (or an attempt to change a
read-only field) never looks like a successful update.

The agent must belong to your organization. Attempting to update an agent
from another organization will return 404.

Authentication:
- API key with READ_WRITE permission, or
- OAuth access token granted the `agents:write` scope
patch/agents/{agent_id}

Path parameters

agent_idstring uuid required

Request body

prompt_instructionsstring nullable

Custom prompt instructions driving the agent's behaviour during a call. Send null to clear them and fall back to the default prompt.

first_messagestring nullable

Initial message the agent says when the conversation starts. Send null to clear it (the agent opens the conversation on its own).

Example request

{
  "first_message": "Hello! How can I help you today?",
  "prompt_instructions": "You are the reception assistant. Be polite and concise. Help guests with check-in, check-out and general inquiries."
}

Response

Successfully updated the agent

okboolean required

Example response

{
  "data": {
    "voice": {
      "ai_provider": "base",
      "custom_name": "Marco",
      "description": "Una voce equilibrata e versatile adatta alla maggior parte delle applicazioni",
      "file": {
        "content_size": 1024,
        "content_type": "audio/mpeg",
        "file_name": "voice.mp3",
        "id": "aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f",
        "url": "https://s3.example.com/some-generated-id/logo.png"
      },
      "id": "aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f",
      "language": "it"
    }
  }
}