PUThttps://app.evoriqa.com/api/v1/chatbots/{chatbotId}/actions

Configure an agent action

Creates or updates the chatbot configuration for one action type. An unknown `type` is a **404**. Only `book_appointment` has a validated `config`, discriminated on `config.provider` — every other action type stores its `config` unvalidated. Within a booking provider each setting is OPTIONAL: a partial config saves cleanly, so an action can be configured before its credential exists. What is validated is the SHAPE of whatever you do send (422 with per-field errors). A config whose `provider` is absent or unrecognised skips validation entirely and is treated as the loose `webhook` default. When `enabled: true` on an API-mode provider (`cal_com`, `calendly`) and a credential is stored, the event type is additionally checked against the live provider: a definitive rejection — token refused, event type not found — is a **422**; an inconclusive check (provider unreachable, or a stored credential that will not decrypt) still saves and returns a `warning` string. The embed providers carry no credential, so no live check runs for them. Connected-mode bookings pass through this same schema, with `connected`, `credentialName`, `eventTypeUri`/`eventTypeId` and `showChip` riding along.

Requires scope chatbots:write

Access is gated — enable it before your first call

The API is off by default. A request succeeds only when all three switches are on: the platform master switch (off by default), your organisation’s API toggle, and your plan or client entitlement. Any one off returns 403 API access is not enabled for this workspace.

Parameters

Name	In	Type	Required	Default	Description
chatbotId	path	string uuid	Required	—	The chatbot's id.

Request body

Content type: application/json

Field	Type	Required	Description
type	string one of `capture_lead` · `escalate_to_human` · `book_appointment` · `get_appointment_slots` · `create_ticket` · `lookup_order` · `http_action`	Required	The action type key. `get_appointment_slots` is derived from `book_appointment` and has no settings of its own, which is why the GET listing omits it.
enabled	boolean	Optional	Whether the action is active. Enabling an API-mode booking provider triggers the live provider check.
config	object	Optional	Action-specific configuration. Validated only for `book_appointment`, per the `provider` variants below; unrelated keys pass through untouched. Every other action type stores this object as sent.
Webhook (default) — `provider: webhook`
config.provider	string the literal `webhook`	Required	The default mode. An absent or unrecognised provider is treated as this one, and skips validation.
config.url	string uri	Optional	Delivery URL for the booking payload. Must be a valid URL when present.
Cal.com API — `provider: cal_com`
config.provider	string the literal `cal_com`	Required
config.credentialName	string	Optional	Name of the stored credential holding the Cal.com API token. Without it, no live check runs.
config.eventTypeId	integer ≥ 1	Optional	The Cal.com event-type id. Must be a positive integer when present; a numeric string is coerced.
config.timeZone	string	Optional	IANA timezone the booking is made in.
config.allowChanges	boolean	Optional	Let customers cancel or reschedule bookings the agent made through this action. Off when absent.
Calendly API — `provider: calendly`
config.provider	string the literal `calendly`	Required
config.credentialName	string	Optional	Name of the stored credential holding the Calendly token.
config.eventTypeUri	string uri	Optional	The Calendly API event-type resource URI. Must be https and on `api.calendly.com` — the verification and booking calls GET it verbatim with your Bearer token, so http would send that credential in cleartext, and a public booking-page URL would 404.
config.timeZone	string	Optional	IANA timezone the booking is made in.
config.allowChanges	boolean	Optional	Let customers cancel bookings the agent made through this action; a reschedule request gets the invitee's own Calendly reschedule link (Calendly has no reschedule API). Off when absent.
Calendly embed (Simple mode) — `provider: calendly_embed`
config.provider	string the literal `calendly_embed`	Required
config.bookingUrl	string uri	Optional	Public booking-page URL. Must be https, on `calendly.com` or a `*.calendly.com` host, and carry a path — a bare domain is not a booking page.
Cal.com embed (Simple mode) — `provider: cal_com_embed`
config.provider	string the literal `cal_com_embed`	Required
config.bookingUrl	string uri	Optional	Public booking-page URL. Must be https, on `cal.com` or `app.cal.com`, and carry a path.

Request

curl

curl -X PUT "https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/actions" \
  -H "x-api-key: $EVORIQA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "capture_lead", "enabled": true }'

Node.js

const res = await fetch("https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/actions", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.EVORIQA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "capture_lead",
    "enabled": true
  }),
});

const responseBody = await res.json();

Python

import os
import requests

res = requests.put(
    "https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/actions",
    headers={"Authorization": f"Bearer {os.environ['EVORIQA_API_KEY']}"},
    json={
      "type": "capture_lead",
      "enabled": True
    },
)

body = res.json()

Response

200 OK

{
  "success": true,
  "data": {
    "id": "7f3a9b21-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "type": "capture_lead",
    "enabled": true
  }
}