# AgentPhone

> Give AI agents their own phone numbers: create agents, route numbers to them, and read back their calls, transcripts, texts and contacts.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/agentphone

## Actions

### Attach number to agent

Route a phone number's calls and texts to an agent. A number belongs to one agent at a time.

**Inputs**

- Agent (`agent_id`, text, required): The agent to act on. Pick one, or paste its id (it starts with agt_).
- Phone number (`number_id`, text, required): The phone number. Pick one, or paste its id (it starts with num_) as returned by 'List phone numbers'.

**Outputs**

- `agentId` (text)
- `number` (object)

**Example output**

```json
{
  "agentId": "agt_8f3a2c1d",
  "number": {
    "id": "num_7b2e9c41",
    "phoneNumber": "+14155550123",
    "status": "active",
    "type": "sms"
  }
}
```

### Create agent

Create an AI agent that answers calls and texts on the numbers you attach to it. Only the name is required.

**Inputs**

- Name (`name`, text, required): The agent's name.
- Description (`description`, text): A note for your own reference.
- Mode (`voice_mode`, text): Hosted: AgentPhone answers from the system prompt below. Webhook: every call and text goes to your own server, which decides the reply. AgentPhone's default is Webhook. One of: `hosted` (Hosted - AgentPhone runs the conversation from a system prompt), `webhook` (Webhook - your server decides every reply).
- System prompt (`system_prompt`, text): What the agent is and how it behaves, used in Hosted mode. At most 20000 characters.
- First message (`begin_message`, text): What the agent says when it answers a call.
- Model tier (`model_tier`, text): Trades speed for capability. AgentPhone's default is Balanced. One of: `turbo` (Turbo - fastest), `balanced`, `max` (Max - most capable), `realtime`.
- Voice (`voice`, text): The voice the agent speaks with. Pick one, or paste a voice id from 'List voices'.
- Language (`language`, text): The language the agent speaks and listens in. One of: `af-ZA` (Afrikaans (South Africa)), `ar-SA` (Arabic (Saudi Arabia)), `az-AZ` (Azerbaijani), `bg-BG` (Bulgarian), `bs-BA` (Bosnian), `ca-ES` (Catalan), `cs-CZ` (Czech), `cy-GB` (Welsh), `da-DK` (Danish), `de-DE` (German), and 53 more.
- Transfer number (`transfer_number`, text): A phone number the agent can hand a call over to, such as +14155550123. A ten-digit number is read as US or Canadian.
- Voicemail message (`voicemail_message`, text): What the agent leaves when a call reaches voicemail.
- Call screening identity (`call_screening_identity`, text): Who the agent says it is when a call-screening service asks.
- Call screening purpose (`call_screening_purpose`, text): Why the agent says it is calling when a call-screening service asks.
- Speech recognition (`stt_mode`, text): Fast or accurate transcription of the caller. One of: `fast`, `accurate`.
- Background sound (`ambient_sound`, text): Ambient sound played under the agent's voice. One of: `none`, `office`, `coffee-shop` (Coffee shop), `outdoor`.
- Noise filtering (`denoising_mode`, text): How much of the caller's background is filtered out. One of: `noise-cancellation` (Cancel noise), `noise-and-background-speech-cancellation` (Cancel noise and background speech).
- Hang up after silence (seconds) (`max_silence_seconds`, number): End the call after this many seconds of silence, from 10 to 3600. AgentPhone's default is 600. From 10 to 3600.
- Speaking speed (`voice_speed`, number): From 0.5 to 2.0; 1 is normal speed. From 0.5 to 2.0.
- Interruption sensitivity (`interruption_sensitivity`, number): How readily the agent stops talking when the caller speaks, from 0 to 1. AgentPhone's default is 0.8. From 0.0 to 1.0.
- Answer texts (`enable_messaging`, text): Whether the agent also handles text messages, not only calls. Leave empty to keep the current setting (on for a new agent). One of: `on` (Turn on), `off` (Turn off).
- Backchannel (`enable_backchannel`, text): Whether the agent makes small listening sounds such as 'mm-hm'. Leave empty to keep the current setting (on for a new agent). One of: `on` (Turn on), `off` (Turn off).

**Outputs**

- `ambientSound` (text)
- `beginMessage` (text)
- `callScreeningIdentity` (text)
- `callScreeningPurpose` (text)
- `createdAt` (text)
- `customTools` (list)
- `denoisingMode` (text)
- `description` (text)
- `enableBackchannel` (true/false)
- `enableMessaging` (true/false)
- `id` (text)
- `interruptionSensitivity` (number)
- `language` (text)
- `maxSilenceMs` (number)
- `modelTier` (text)
- `name` (text)
- `numbers` (list)
- `sttMode` (text)
- `systemPrompt` (text)
- `transferNumber` (text)
- `voice` (text)
- `voiceMode` (text)
- `voiceSpeed` (number)
- `voicemailMessage` (text)

**Example output**

```json
{
  "ambientSound": "none",
  "beginMessage": "Hi, thanks for calling the clinic.",
  "callScreeningIdentity": null,
  "callScreeningPurpose": null,
  "createdAt": "2026-10-01T10:15:00Z",
  "customTools": null,
  "denoisingMode": "noise-cancellation",
  "description": "Answers the clinic line.",
  "enableBackchannel": true,
  "enableMessaging": true,
  "id": "agt_8f3a2c1d",
  "interruptionSensitivity": 0.8,
  "language": "en-US",
  "maxSilenceMs": 600000,
  "modelTier": "balanced",
  "name": "Front desk",
  "numbers": [
    {
      "id": "num_7b2e9c41",
      "phoneNumber": "+14155550123",
      "status": "active",
      "type": "sms"
    }
  ],
  "sttMode": "fast",
  "systemPrompt": "You answer calls for a dental clinic.",
  "transferNumber": null,
  "voice": "voice_ava",
  "voiceMode": "hosted",
  "voiceSpeed": 1.0,
  "voicemailMessage": null
}
```

### Create contact

Add a contact. Each phone number can belong to only one contact.

**Inputs**

- Phone number (`phone_number`, text, required): The contact's phone number, in any common format, such as +14155550188.
- Name (`name`, text, required): The contact's name.
- Email (`email`, text): The contact's email address.
- Notes (`notes`, text): Anything worth remembering about the contact.

**Outputs**

- `createdAt` (text)
- `email` (text)
- `id` (text)
- `name` (text)
- `notes` (text)
- `phoneNumber` (text)
- `updatedAt` (text)

**Example output**

```json
{
  "createdAt": "2026-10-02T09:00:00Z",
  "email": "ada@example.com",
  "id": "ct_2d7e5a90",
  "name": "Ada Lovelace",
  "notes": "Prefers texts.",
  "phoneNumber": "+14155550188",
  "updatedAt": "2026-10-02T09:00:00Z"
}
```

### Delete agent

Delete an agent. Its numbers, conversations and calls are kept and simply no longer point at it.

**Inputs**

- Agent (`agent_id`, text, required): The agent to act on. Pick one, or paste its id (it starts with agt_).

**Outputs**

- `id` (text)
- `name` (text)
- `success` (true/false)

**Example output**

```json
{
  "id": "agt_8f3a2c1d",
  "name": "Front desk",
  "success": true
}
```

### Delete contact

Delete a contact. Their conversations and calls are kept.

**Inputs**

- Contact (`contact_id`, text, required): The contact's id, as returned by 'List contacts' or 'Create contact'.

**Outputs**

- `deleted` (true/false)
- `id` (text)

**Example output**

```json
{
  "deleted": true,
  "id": "ct_2d7e5a90"
}
```

### Detach number from agent

Stop routing a phone number to an agent. The number stays on your account and keeps receiving calls and texts.

**Inputs**

- Agent (`agent_id`, text, required): The agent to act on. Pick one, or paste its id (it starts with agt_).
- Phone number (`number_id`, text, required): The phone number. Pick one, or paste its id (it starts with num_) as returned by 'List phone numbers'.

**Outputs**

- `agent_id` (text)
- `detached` (true/false)
- `number_id` (text)
- `response` (object)

**Example output**

```json
{
  "agent_id": "agt_8f3a2c1d",
  "detached": true,
  "number_id": "num_7b2e9c41",
  "response": null
}
```

### Get agent

One agent's full configuration and the numbers attached to it.

**Inputs**

- Agent (`agent_id`, text, required): The agent to act on. Pick one, or paste its id (it starts with agt_).

**Outputs**

- `ambientSound` (text)
- `beginMessage` (text)
- `callScreeningIdentity` (text)
- `callScreeningPurpose` (text)
- `createdAt` (text)
- `customTools` (list)
- `denoisingMode` (text)
- `description` (text)
- `enableBackchannel` (true/false)
- `enableMessaging` (true/false)
- `id` (text)
- `interruptionSensitivity` (number)
- `language` (text)
- `maxSilenceMs` (number)
- `modelTier` (text)
- `name` (text)
- `numbers` (list)
- `sttMode` (text)
- `systemPrompt` (text)
- `transferNumber` (text)
- `voice` (text)
- `voiceMode` (text)
- `voiceSpeed` (number)
- `voicemailMessage` (text)

**Example output**

```json
{
  "ambientSound": "none",
  "beginMessage": "Hi, thanks for calling the clinic.",
  "callScreeningIdentity": null,
  "callScreeningPurpose": null,
  "createdAt": "2026-10-01T10:15:00Z",
  "customTools": null,
  "denoisingMode": "noise-cancellation",
  "description": "Answers the clinic line.",
  "enableBackchannel": true,
  "enableMessaging": true,
  "id": "agt_8f3a2c1d",
  "interruptionSensitivity": 0.8,
  "language": "en-US",
  "maxSilenceMs": 600000,
  "modelTier": "balanced",
  "name": "Front desk",
  "numbers": [
    {
      "id": "num_7b2e9c41",
      "phoneNumber": "+14155550123",
      "status": "active",
      "type": "sms"
    }
  ],
  "sttMode": "fast",
  "systemPrompt": "You answer calls for a dental clinic.",
  "transferNumber": null,
  "voice": "voice_ava",
  "voiceMode": "hosted",
  "voiceSpeed": 1.0,
  "voicemailMessage": null
}
```

### Get call

One call with its full transcript, turn by turn.

**Inputs**

- Call (`call_id`, text, required): The call's id, as returned by 'List calls'.

**Outputs**

- `agentId` (text)
- `agentName` (text)
- `direction` (text)
- `durationSeconds` (number)
- `endedAt` (text)
- `fromNumber` (text)
- `id` (text)
- `lastTranscriptSnippet` (text)
- `phoneNumber` (text)
- `phoneNumberId` (text)
- `recordingAvailable` (true/false)
- `recordingUrl` (text)
- `startedAt` (text)
- `status` (text)
- `toNumber` (text)
- `transcripts` (list)

**Example output**

```json
{
  "agentId": "agt_8f3a2c1d",
  "direction": "inbound",
  "durationSeconds": 130,
  "endedAt": "2026-10-02T16:02:10Z",
  "fromNumber": "+14155550188",
  "id": "call_9a4f6b28",
  "lastTranscriptSnippet": "See you Friday.",
  "phoneNumber": "+14155550123",
  "phoneNumberId": "num_7b2e9c41",
  "recordingAvailable": false,
  "startedAt": "2026-10-02T16:00:00Z",
  "status": "completed",
  "toNumber": "+14155550123",
  "transcripts": [
    {
      "createdAt": "2026-10-02T16:00:20Z",
      "id": "tr_1",
      "response": "Of course - Friday at 10 works. See you Friday.",
      "transcript": "Can I move my appointment to Friday?"
    }
  ]
}
```

### Get conversation

One conversation with its most recent messages and what can be sent in it.

**Inputs**

- Conversation (`conversation_id`, text, required): The conversation's id, as returned by 'List conversations'.
- Messages to include (`message_limit`, number): How many recent messages to include, from 1 to 100. Defaults to 50. From 1 to 100. Default: `50`.

**Outputs**

- `agentId` (text)
- `capabilities` (object)
- `channel` (text)
- `createdAt` (text)
- `groupIconUrl` (text)
- `groupId` (text)
- `groupName` (text)
- `id` (text)
- `isGroup` (true/false)
- `lastMessageAt` (text)
- `messageCount` (number)
- `messages` (list)
- `metadata` (object)
- `participant` (text)
- `participants` (list)
- `phoneNumber` (text)
- `phoneNumberId` (text)

**Example output**

```json
{
  "agentId": "agt_8f3a2c1d",
  "capabilities": {
    "canSendMessages": true,
    "emojiReactions": false,
    "media": true,
    "reactions": false
  },
  "channel": "native",
  "createdAt": "2026-10-02T15:04:00Z",
  "id": "conv_3e8d1f07",
  "isGroup": false,
  "lastMessageAt": "2026-10-02T15:04:00Z",
  "messageCount": 1,
  "messages": [
    {
      "body": "Can I move my appointment to Friday?",
      "channel": "sms",
      "direction": "inbound",
      "fromNumber": "+14155550188",
      "id": "msg_51c0a9e2",
      "mediaUrls": [],
      "receivedAt": "2026-10-02T15:04:00Z",
      "status": "received",
      "toNumber": "+14155550123"
    }
  ],
  "metadata": null,
  "participant": "+14155550188",
  "phoneNumber": "+14155550123",
  "phoneNumberId": "num_7b2e9c41"
}
```

### Get usage

Your phone-number allowance, message and call counts for the last day, week and month, and webhook delivery statistics.

**Inputs**: None.

**Outputs**

- `numbers` (object)
- `periodEnd` (text)
- `periodStart` (text)
- `reportGeneratedAt` (text)
- `stats` (object)

**Example output**

```json
{
  "numbers": {
    "limit": 5,
    "remaining": 4,
    "used": 1
  },
  "periodEnd": "2026-10-12T00:00:00Z",
  "periodStart": "2026-09-12T00:00:00Z",
  "reportGeneratedAt": "2026-10-12T08:00:00Z",
  "stats": {
    "callsLast24h": 1,
    "callsLast30d": 3,
    "callsLast7d": 3,
    "failedWebhookDeliveries": 0,
    "messagesLast24h": 2,
    "messagesLast30d": 12,
    "messagesLast7d": 9,
    "smsSegmentsLast30d": 14,
    "successfulWebhookDeliveries": 0,
    "totalCalls": 3,
    "totalMessages": 12,
    "totalWebhookDeliveries": 0
  }
}
```

### List agents

The agents on your AgentPhone account, with the numbers attached to each.

**Inputs**

- Maximum records (`limit`, number): The most records to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.
- Skip (`offset`, number): How many records to skip, for the next page. Use the previous step's next_offset. Defaults to 0. From 0 to 1000000. Default: `0`.

**Outputs**

- `agents` (list): The agents returned
- `count` (number): How many agents came back
- `has_more` (true/false): Whether more records are available
- `next_offset` (number): The offset for the next page, empty when none
- `total` (number): How many agents there are in total

**Example output**

```json
{
  "agents": [
    {
      "ambientSound": "none",
      "beginMessage": "Hi, thanks for calling the clinic.",
      "callScreeningIdentity": null,
      "callScreeningPurpose": null,
      "createdAt": "2026-10-01T10:15:00Z",
      "customTools": null,
      "denoisingMode": "noise-cancellation",
      "description": "Answers the clinic line.",
      "enableBackchannel": true,
      "enableMessaging": true,
      "id": "agt_8f3a2c1d",
      "interruptionSensitivity": 0.8,
      "language": "en-US",
      "maxSilenceMs": 600000,
      "modelTier": "balanced",
      "name": "Front desk",
      "numbers": [
        {
          "id": "num_7b2e9c41",
          "phoneNumber": "+14155550123",
          "status": "active",
          "type": "sms"
        }
      ],
      "sttMode": "fast",
      "systemPrompt": "You answer calls for a dental clinic.",
      "transferNumber": null,
      "voice": "voice_ava",
      "voiceMode": "hosted",
      "voiceSpeed": 1.0,
      "voicemailMessage": null
    }
  ],
  "count": 1,
  "has_more": false,
  "next_offset": null,
  "total": 1
}
```

### List calls

Calls on your account, newest first, with a snippet of each transcript.

**Inputs**

- Status (`status`, text): Only calls in this state. Leave empty for all. One of: `completed`, `in-progress` (In progress), `failed`.
- Direction (`direction`, text): Only calls in this direction. Leave empty for all. One of: `inbound`, `outbound`, `web`.
- Call type (`call_type`, text): Only phone-network or only browser calls. Leave empty for both. One of: `pstn` (Phone network), `web`.
- Phone number contains (`search`, text): Only calls whose caller or called number contains these digits.
- Maximum records (`limit`, number): The most records to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.
- Skip (`offset`, number): How many records to skip, for the next page. Use the previous step's next_offset. Defaults to 0. From 0 to 1000000. Default: `0`.

**Outputs**

- `calls` (list): The calls returned
- `count` (number): How many calls came back
- `has_more` (true/false): Whether more records are available
- `next_offset` (number): The offset for the next page, empty when none
- `total` (number): How many calls there are in total

**Example output**

```json
{
  "calls": [
    {
      "agentId": "agt_8f3a2c1d",
      "direction": "inbound",
      "durationSeconds": 130,
      "endedAt": "2026-10-02T16:02:10Z",
      "fromNumber": "+14155550188",
      "id": "call_9a4f6b28",
      "lastTranscriptSnippet": "See you Friday.",
      "phoneNumber": "+14155550123",
      "phoneNumberId": "num_7b2e9c41",
      "recordingAvailable": false,
      "startedAt": "2026-10-02T16:00:00Z",
      "status": "completed",
      "toNumber": "+14155550123"
    }
  ],
  "count": 1,
  "has_more": false,
  "next_offset": null,
  "total": 1
}
```

### List contacts

Your AgentPhone contacts, optionally narrowed by a search.

**Inputs**

- Search (`search`, text): Only contacts matching this text.
- Maximum records (`limit`, number): The most contacts to return, from 1 to 200. Defaults to 50. From 1 to 200. Default: `50`.
- Skip (`offset`, number): How many records to skip, for the next page. Use the previous step's next_offset. Defaults to 0. From 0 to 1000000. Default: `0`.

**Outputs**

- `contacts` (list): The contacts returned
- `count` (number): How many contacts came back
- `has_more` (true/false): Whether more records are available
- `next_offset` (number): The offset for the next page, empty when none
- `total` (number): How many contacts there are in total

**Example output**

```json
{
  "contacts": [
    {
      "createdAt": "2026-10-02T09:00:00Z",
      "email": "ada@example.com",
      "id": "ct_2d7e5a90",
      "name": "Ada Lovelace",
      "notes": "Prefers texts.",
      "phoneNumber": "+14155550188",
      "updatedAt": "2026-10-02T09:00:00Z"
    }
  ],
  "count": 1,
  "has_more": false,
  "next_offset": null,
  "total": 1
}
```

### List conversation messages

A conversation's messages, newest first. For older ones, pass the previous step's oldest_received_at as Before.

**Inputs**

- Conversation (`conversation_id`, text, required): The conversation's id, as returned by 'List conversations'.
- Maximum messages (`limit`, number): The most messages to return, from 1 to 200. Defaults to 50. From 1 to 200. Default: `50`.
- Before (`before`, date and time): Only messages received before this moment.
- After (`after`, date and time): Only messages received after this moment.

**Outputs**

- `count` (number): How many messages came back
- `has_more` (true/false): Whether older messages are available
- `messages` (list): The messages returned, newest first
- `oldest_received_at` (text): The oldest message's time. Pass it as 'Before' to fetch the next, older page.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "messages": [
    {
      "body": "Can I move my appointment to Friday?",
      "channel": "sms",
      "direction": "inbound",
      "fromNumber": "+14155550188",
      "id": "msg_51c0a9e2",
      "mediaUrls": [],
      "receivedAt": "2026-10-02T15:04:00Z",
      "status": "received",
      "toNumber": "+14155550123"
    }
  ],
  "oldest_received_at": "2026-10-02T15:04:00Z"
}
```

### List conversations

Text conversations across your numbers, most recent first, with a preview of the last message.

**Inputs**

- Maximum records (`limit`, number): The most records to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.
- Skip (`offset`, number): How many records to skip, for the next page. Use the previous step's next_offset. Defaults to 0. From 0 to 1000000. Default: `0`.

**Outputs**

- `conversations` (list): The conversations returned
- `count` (number): How many conversations came back
- `has_more` (true/false): Whether more records are available
- `next_offset` (number): The offset for the next page, empty when none
- `total` (number): How many conversations there are in total

**Example output**

```json
{
  "conversations": [
    {
      "agentId": "agt_8f3a2c1d",
      "channel": "native",
      "createdAt": "2026-10-02T15:04:00Z",
      "id": "conv_3e8d1f07",
      "isGroup": false,
      "lastMessageAt": "2026-10-02T15:04:00Z",
      "lastMessagePreview": "Can I move my appointment to Friday?",
      "messageCount": 1,
      "metadata": null,
      "participant": "+14155550188",
      "phoneNumber": "+14155550123",
      "phoneNumberId": "num_7b2e9c41"
    }
  ],
  "count": 1,
  "has_more": false,
  "next_offset": null,
  "total": 1
}
```

### List phone numbers

The active phone numbers on your account, with the agent each is attached to and whether it can send texts yet.

**Inputs**

- External id (`external_id`, text): Only the number tagged with this external id when it was bought. Leave empty for all of them.
- Maximum records (`limit`, number): The most records to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.
- Skip (`offset`, number): How many records to skip, for the next page. Use the previous step's next_offset. Defaults to 0. From 0 to 1000000. Default: `0`.

**Outputs**

- `count` (number): How many numbers came back
- `has_more` (true/false): Whether more records are available
- `next_offset` (number): The offset for the next page, empty when none
- `numbers` (list): The numbers returned
- `total` (number): How many numbers there are in total

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "next_offset": null,
  "numbers": [
    {
      "agentId": "agt_8f3a2c1d",
      "country": "US",
      "createdAt": "2026-10-01T10:20:00Z",
      "dailyNewContacts": {
        "limit": 50,
        "used": 0
      },
      "externalId": null,
      "id": "num_7b2e9c41",
      "inboundCallsEnabled": true,
      "outboundSms": "registration_required",
      "phoneNumber": "+14155550123",
      "purchasedAt": "2026-10-01T10:20:00Z",
      "readReceiptsEnabled": false,
      "status": "active",
      "type": "sms",
      "whatsappEnabled": false
    }
  ],
  "total": 1
}
```

### List voices

Every voice an agent can speak with, with its id for the Voice field.

**Inputs**: None.

**Outputs**

- `count` (number): How many voices came back
- `voices` (list): Every voice an agent can use

**Example output**

```json
{
  "count": 1,
  "voices": [
    {
      "accent": "american",
      "gender": "female",
      "preview_audio_url": null,
      "provider": "elevenlabs",
      "voice_id": "voice_ava",
      "voice_name": "Ava"
    }
  ]
}
```

### Provision phone number

Buy a US or Canadian phone number. It costs $3.00 a month, and the first month comes off your balance immediately - a new account's $5.00 credit covers one.

**Inputs**

- Country (`country`, text): Where the number is from. Defaults to the US. One of: `US` (United States), `CA` (Canada). Default: `US`.
- Area code (`area_code`, text): A three-digit area code, such as 415. Leave empty for any available number.
- Agent (`agent_id`, text): An agent to attach the new number to straight away. Leave empty to attach it later.
- External id (`external_id`, text): Your own reference for the number, for finding it again with 'List phone numbers'.

**Outputs**

- `agentId` (text)
- `country` (text)
- `createdAt` (text)
- `dailyNewContacts` (object)
- `externalId` (text)
- `id` (text)
- `inboundCallsEnabled` (true/false)
- `outboundSms` (text)
- `phoneNumber` (text)
- `purchasedAt` (text)
- `readReceiptsEnabled` (true/false)
- `status` (text)
- `type` (text)
- `whatsappEnabled` (true/false)

**Example output**

```json
{
  "agentId": "agt_8f3a2c1d",
  "country": "US",
  "createdAt": "2026-10-01T10:20:00Z",
  "dailyNewContacts": {
    "limit": 50,
    "used": 0
  },
  "externalId": null,
  "id": "num_7b2e9c41",
  "inboundCallsEnabled": true,
  "outboundSms": "registration_required",
  "phoneNumber": "+14155550123",
  "purchasedAt": "2026-10-01T10:20:00Z",
  "readReceiptsEnabled": false,
  "status": "active",
  "type": "sms",
  "whatsappEnabled": false
}
```

### Update agent

Change an agent. Only the fields you fill in change; the rest stay as they are, and the change applies to the next call or text.

**Inputs**

- Agent (`agent_id`, text, required): The agent to act on. Pick one, or paste its id (it starts with agt_).
- Name (`name`, text): A new name for the agent. Leave empty to keep the current one.
- Description (`description`, text): A note for your own reference.
- Mode (`voice_mode`, text): Hosted: AgentPhone answers from the system prompt below. Webhook: every call and text goes to your own server, which decides the reply. AgentPhone's default is Webhook. One of: `hosted` (Hosted - AgentPhone runs the conversation from a system prompt), `webhook` (Webhook - your server decides every reply).
- System prompt (`system_prompt`, text): What the agent is and how it behaves, used in Hosted mode. At most 20000 characters.
- First message (`begin_message`, text): What the agent says when it answers a call.
- Model tier (`model_tier`, text): Trades speed for capability. AgentPhone's default is Balanced. One of: `turbo` (Turbo - fastest), `balanced`, `max` (Max - most capable), `realtime`.
- Voice (`voice`, text): The voice the agent speaks with. Pick one, or paste a voice id from 'List voices'.
- Language (`language`, text): The language the agent speaks and listens in. One of: `af-ZA` (Afrikaans (South Africa)), `ar-SA` (Arabic (Saudi Arabia)), `az-AZ` (Azerbaijani), `bg-BG` (Bulgarian), `bs-BA` (Bosnian), `ca-ES` (Catalan), `cs-CZ` (Czech), `cy-GB` (Welsh), `da-DK` (Danish), `de-DE` (German), and 53 more.
- Transfer number (`transfer_number`, text): A phone number the agent can hand a call over to, such as +14155550123. A ten-digit number is read as US or Canadian.
- Voicemail message (`voicemail_message`, text): What the agent leaves when a call reaches voicemail.
- Call screening identity (`call_screening_identity`, text): Who the agent says it is when a call-screening service asks.
- Call screening purpose (`call_screening_purpose`, text): Why the agent says it is calling when a call-screening service asks.
- Speech recognition (`stt_mode`, text): Fast or accurate transcription of the caller. One of: `fast`, `accurate`.
- Background sound (`ambient_sound`, text): Ambient sound played under the agent's voice. One of: `none`, `office`, `coffee-shop` (Coffee shop), `outdoor`.
- Noise filtering (`denoising_mode`, text): How much of the caller's background is filtered out. One of: `noise-cancellation` (Cancel noise), `noise-and-background-speech-cancellation` (Cancel noise and background speech).
- Hang up after silence (seconds) (`max_silence_seconds`, number): End the call after this many seconds of silence, from 10 to 3600. AgentPhone's default is 600. From 10 to 3600.
- Speaking speed (`voice_speed`, number): From 0.5 to 2.0; 1 is normal speed. From 0.5 to 2.0.
- Interruption sensitivity (`interruption_sensitivity`, number): How readily the agent stops talking when the caller speaks, from 0 to 1. AgentPhone's default is 0.8. From 0.0 to 1.0.
- Answer texts (`enable_messaging`, text): Whether the agent also handles text messages, not only calls. Leave empty to keep the current setting (on for a new agent). One of: `on` (Turn on), `off` (Turn off).
- Backchannel (`enable_backchannel`, text): Whether the agent makes small listening sounds such as 'mm-hm'. Leave empty to keep the current setting (on for a new agent). One of: `on` (Turn on), `off` (Turn off).

**Outputs**

- `ambientSound` (text)
- `beginMessage` (text)
- `callScreeningIdentity` (text)
- `callScreeningPurpose` (text)
- `createdAt` (text)
- `customTools` (list)
- `denoisingMode` (text)
- `description` (text)
- `enableBackchannel` (true/false)
- `enableMessaging` (true/false)
- `id` (text)
- `interruptionSensitivity` (number)
- `language` (text)
- `maxSilenceMs` (number)
- `modelTier` (text)
- `name` (text)
- `numbers` (list)
- `sttMode` (text)
- `systemPrompt` (text)
- `transferNumber` (text)
- `voice` (text)
- `voiceMode` (text)
- `voiceSpeed` (number)
- `voicemailMessage` (text)

**Example output**

```json
{
  "ambientSound": "none",
  "beginMessage": "Hi, thanks for calling the clinic.",
  "callScreeningIdentity": null,
  "callScreeningPurpose": null,
  "createdAt": "2026-10-01T10:15:00Z",
  "customTools": null,
  "denoisingMode": "noise-cancellation",
  "description": "Answers the clinic line.",
  "enableBackchannel": true,
  "enableMessaging": true,
  "id": "agt_8f3a2c1d",
  "interruptionSensitivity": 0.8,
  "language": "en-US",
  "maxSilenceMs": 600000,
  "modelTier": "balanced",
  "name": "Front desk",
  "numbers": [
    {
      "id": "num_7b2e9c41",
      "phoneNumber": "+14155550123",
      "status": "active",
      "type": "sms"
    }
  ],
  "sttMode": "fast",
  "systemPrompt": "You answer calls for a dental clinic.",
  "transferNumber": null,
  "voice": "voice_ava",
  "voiceMode": "hosted",
  "voiceSpeed": 1.0,
  "voicemailMessage": null
}
```

### Update contact

Change a contact. Only the fields you fill in change.

**Inputs**

- Contact (`contact_id`, text, required): The contact's id, as returned by 'List contacts' or 'Create contact'.
- Phone number (`phone_number`, text): A new phone number. It must not belong to another contact. Leave empty to keep the current one.
- Name (`name`, text): A new name. Leave empty to keep the current one.
- Email (`email`, text): A new email address. Leave empty to keep it.
- Notes (`notes`, text): New notes. Leave empty to keep the current ones.

**Outputs**

- `createdAt` (text)
- `email` (text)
- `id` (text)
- `name` (text)
- `notes` (text)
- `phoneNumber` (text)
- `updatedAt` (text)

**Example output**

```json
{
  "createdAt": "2026-10-02T09:00:00Z",
  "email": "ada@example.com",
  "id": "ct_2d7e5a90",
  "name": "Ada Lovelace",
  "notes": "Prefers texts.",
  "phoneNumber": "+14155550188",
  "updatedAt": "2026-10-02T09:00:00Z"
}
```