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

# Create an action

> Create a built-in action an agent can take: calendar, transfer, SMS, email, WhatsApp or Slack.

> [!NOTE]
>
> This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](https://docs.nedzo.ai/api-reference/introduction.md#plan-access).

An action is something the agent can do during a conversation, like book a meeting or send a text. Returns `201` with the new action.

## Path Parameters

**agentId** `string` *required*

Agent UUID

**kind** `string` *required*

The kind of action: `calendar`, `transfer`, `sms`, `email`, `whatsapp` or `slack`.

## Body

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

**calendarType** `string` *required*

`cal_com`, `calendly`, `leadconnector` or `google`. The provider must be connected in the dashboard.

**calendarId** `string`

A calendar or event type id from [List calendars](https://docs.nedzo.ai/api-reference/agents/calendars.md).

**timezone** `string`

An IANA time zone like `America/New_York`. Leave it out and the agent asks the contact.

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

**transferType** `string` *required*

`warm` (the agent introduces the caller first) or `cold` (it hands the call straight over).

**transferNumber** `string` *required*

The number to transfer to, in E.164 format like `+14155551234`.

**transferSentence** `string` *required*

What the agent says before it transfers.

### SMS

**phoneNumberId** `string` *required*

The number to send from. It must be a number in the agent's workspace.

**recipientType** `string`

`contact` sends to the person in the conversation, `specific` sends to `recipientValue`, and `ask` lets the agent ask. Leave it out for `contact`.

**recipientValue** `string`

The number to send to. Needed when `recipientType` is `specific`.

**messageTemplate** `string` *required*

The message. It can use `{{variables}}` from `parameters`.

**parameters** `object[]`

Values the agent fills in from the conversation.

### WhatsApp

**whatsappSenderId** `string`

The connected WhatsApp number to send from. It must be in the agent's workspace. Required unless you send `phoneNumberId`.

**phoneNumberId** `string`

The older way to pick the sender: a phone number in the agent's workspace whose WhatsApp number sends the message. Send `whatsappSenderId` instead.

**messageMode** `string` (default: fixed)

`fixed` sends `messageTemplate`. `ai_generated` lets the agent write the message.

**messageTemplate** `string`

The message, up to 1,600 characters. It can use `{{variables}}` from `parameters`. Required when `messageMode` is `fixed`.

**recipientType** `string`

`contact`, `specific` or `ask`, as for SMS. Leave it out for `contact`.

**recipientValue** `string`

The number to send to. Needed when `recipientType` is `specific`.

**parameters** `object[]`

Values the agent fills in from the conversation.

The response does not include `whatsappSenderId`.

### Email

**fromName** `string` *required*

The sender name.

**fromAddress** `string` *required*

The part of the sender address before the `@`, like `support`.

**subject** `string` *required*

The subject line.

**body** `string` *required*

The plain text body.

**bodyHtml** `string`

The HTML body.

**recipientType** `string` *required*

`contact`, `specific` or `ask`, as above.

**recipientValue** `string`

The address to send to. Needed when `recipientType` is `specific`.

**emailSenderAddressId** `string`

A sender address in the workspace. Leave it out to use the default.

### Slack

**channelId** `string` *required*

The Slack channel to post in. Slack must be connected in the dashboard.

**channelName** `string`

The channel's name, for display.

**messageTemplate** `string` *required*

The message.

```bash cURL theme={null}
curl -X POST "https://api.nedzo.ai/v1/agents/123e4567-e89b-12d3-a456-426614174000/actions/sms" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Send booking link",
      "condition": "The caller wants to book",
      "phoneNumberId": "8f14e45f-ceea-467a-9575-0d3c8f9e1a9b",
      "messageTemplate": "Book here: https://example.com/book"
    }'
```

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

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

## 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 is not in your API key's scope, `whatsappSenderId` is not a WhatsApp number in the agent's workspace, or `{kind}` is not one of the six. |


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