> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent actions

> Create and manage the built-in actions an agent can take: calendar, transfer, SMS, email, WhatsApp and Slack.

<Note>
  These endpoints are for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

An action is something the agent can do during a conversation, like book a meeting or send a text. Each kind has the same five endpoints. Replace `{kind}` with `calendar`, `transfer`, `sms`, `email`, `whatsapp` or `slack`.

| Method | Path | What it does |
| - | - | - |
| `GET` | `/v1/agents/{agentId}/actions/{kind}` | List the agent's actions of this kind |
| `POST` | `/v1/agents/{agentId}/actions/{kind}` | Create one. Returns `201`. |
| `GET` | `/v1/agents/{agentId}/actions/{kind}/{actionId}` | Get one |
| `PATCH` | `/v1/agents/{agentId}/actions/{kind}/{actionId}` | Update one. Send only the fields to change. |
| `DELETE` | `/v1/agents/{agentId}/actions/{kind}/{actionId}` | Delete one. Returns `204`. |

Every action has `name` (required when you create one), `condition` (when the agent should use it) and `isActive`. The fields for each kind are below. The API checks the same rules as the dashboard's server.

## Calendar

<ParamField body="calendarType" type="string" required>
  `cal_com`, `calendly`, `leadconnector` or `google`. The provider must be connected in the dashboard.
</ParamField>

<ParamField body="calendarId" type="string">
  A calendar or event type id from [List calendars](/api-reference/agents/calendars).
</ParamField>

<ParamField body="timezone" type="string">
  An IANA time zone like `America/New_York`. Leave it out and the agent asks the contact.
</ParamField>

A calendar action also adds booking steps to the agent's prompt, the same as in the dashboard.

## Transfer

Transfer actions work on voice agents only, the same as in the dashboard. A chat or widget agent gets a `400`.

<ParamField body="transferType" type="string" required>
  `warm` (the agent introduces the caller first) or `cold` (it hands the call straight over).
</ParamField>

<ParamField body="transferNumber" type="string" required>
  The number to transfer to, in E.164 format like `+14155551234`.
</ParamField>

<ParamField body="transferSentence" type="string" required>
  What the agent says before it transfers. On an update you may leave it out, but you can't set it to empty.
</ParamField>

## SMS and WhatsApp

<ParamField body="phoneNumberId" type="string" required>
  The number to send from. It must be a number in the agent's workspace.
</ParamField>

<ParamField body="recipientType" type="string">
  `contact` sends to the person in the conversation, `specific` sends to `recipientValue`, and `ask` lets the agent ask. Leave it out for `contact`.
</ParamField>

<ParamField body="recipientValue" type="string">
  The number to send to. Needed when `recipientType` is `specific`.
</ParamField>

<ParamField body="messageTemplate" type="string" required>
  The message. It can use `{{variables}}` from `parameters`. Required for SMS. WhatsApp needs it too, since `fixed` is the only message mode today.
</ParamField>

<ParamField body="parameters" type="object[]">
  Values the agent fills in from the conversation.
</ParamField>

## Email

<ParamField body="fromName" type="string" required>The sender name.</ParamField>
<ParamField body="fromAddress" type="string" required>The part of the sender address before the `@`, like `support`.</ParamField>
<ParamField body="subject" type="string" required>The subject line.</ParamField>
<ParamField body="body" type="string" required>The plain text body.</ParamField>
<ParamField body="bodyHtml" type="string">The HTML body.</ParamField>
<ParamField body="recipientType" type="string" required>`contact`, `specific` or `ask`, as above.</ParamField>
<ParamField body="recipientValue" type="string">The address to send to. Needed when `recipientType` is `specific`.</ParamField>
<ParamField body="emailSenderAddressId" type="string">A sender address in the workspace. Leave it out to use the default.</ParamField>

## Slack

<ParamField body="channelId" type="string" required>The Slack channel to post in. Slack must be connected in the dashboard.</ParamField>
<ParamField body="channelName" type="string">The channel's name, for display.</ParamField>
<ParamField body="messageTemplate" type="string" required>The message.</ParamField>

## Response

Each action comes back with its `id`, `kind`, `agentId`, its fields, `createdAt` and `updatedAt`.

```json Response theme={null}
{
  "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "kind": "sms",
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Send booking link",
  "condition": "The caller wants to book",
  "isActive": true,
  "phoneNumberId": "8f14e45f-ceea-467a-9575-0d3c8f9e1a9b",
  "recipientType": "contact",
  "recipientValue": null,
  "messageTemplate": "Book here: https://example.com/book",
  "messageMode": "fixed",
  "parameters": [],
  "createdAt": "2026-10-11T10:00:00Z",
  "updatedAt": "2026-10-11T10:00:00Z"
}
```

## Errors

| Status | When |
| - | - |
| `400` | A field is missing or wrong, `phoneNumberId` is not a number in the agent's workspace, or a transfer is on a chat or widget agent. |
| `404` | The agent or the action is not in your API key's scope, the action belongs to another agent, or `{kind}` is not one of the six. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.