Backend API

The Backend API lets you programmatically access your Zipchat conversation data and manage your AI's configuration. Sync conversations with your CRM, reply to customers, and update the master prompt,

The Backend API lets you programmatically access your Zipchat conversation data and manage your AI's configuration. Use it to sync conversations with your CRM, build custom analytics dashboards, take over conversations from the AI, reply to customers, and update the master prompt, custom tools (skills), and variables — all from your own systems.

Getting Started

1. Go to Settings > Integrations in your Zipchat dashboard

2. Click Enable on the Backend API card

3. Copy your API key (prefixed with zc-) — store it securely, it is only shown once

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer zc-your_api_key_here

All requests must be authenticated. Unauthenticated or invalid requests return 401 Unauthorized.

The API accepts two kinds of token, interchangeably, on every endpoint:

Chat-level tokens (zc-)

Scoped to a single chat. Generated per chat in Settings > Integrations > Backend API. A chat token only authenticates requests whose :chat_id matches the chat it belongs to — any other chat_id returns 401.

User-level tokens (zcu-)

Personal to a user and work against any chat that user can access (chats they own or are a member of). Generate or regenerate one under Account > Settings (/account/settings/edit). Use the same Authorization: Bearer zcu-... header. A user token used against a chat_id the user cannot access returns 401 and never reveals whether that chat exists.

Both token types can call every endpoint below. Two caveats for user tokens:

• Role model: configuration writes (updating the prompt, creating/updating/deleting custom tools and variables) follow the same permissions as the dashboard. A member-role (read-only) user's token receives 403 Forbidden on those endpoints but can still use all read and conversation endpoints.

• Revocation: user tokens authenticate independently of the chat's Backend API integration — disabling that integration revokes only the chat-level zc- key. To cut off a user token, revoke it in that user's Account > Settings, or remove the user from the chat.

Tokens are environment-specific: a token generated in production only works against production, and vice versa for staging/local environments.

Base URL

https://app.zipchat.ai/api/integrations/backend_api/v1

Endpoints

List Chats

GET /chats

Lists the chats reachable with your credential, so clients can discover chat ids. With a user token this returns every chat the user can access; with a chat token it returns only that token's chat.

Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	50	Items per page (max 100)

Response

{
  "chats": [
    {
      "id": 1,
      "name": "Acme Store AI",
      "domain": "acme-store.com",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1,
    "has_next_page": false
  }
}

---

List Conversations

GET /chats/:chat_id/conversations

Returns a paginated list of conversations for the given chat.

Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	50	Items per page (max 100)
last_message_at_since	string	—	ISO 8601 timestamp. Only return conversations with activity since this time.

Response

{
  "conversations": [
    {
      "id": 12345,
      "chat_id": 1,
      "created_at": "2026-01-15T10:30:00Z",
      "last_message_at": "2026-01-15T10:45:00Z",
      "channel": "web",
      "manual_reply_mode": false,
      "last_escalated_at": null,
      "last_escalation_resolved_at": null,
      "assignee": null,
      "share_url": "https://app.zipchat.ai/chats/1/conversations/12345",
      "lead": {
        "id": 100,
        "full_name": "John Doe",
        "email": "[e-mail]",
        "phone_number": "[phone]",
        "email_marketing_consent": true
      }
    },
    {
      "id": 12346,
      "chat_id": 1,
      "created_at": "2026-01-15T11:00:00Z",
      "last_message_at": "2026-01-15T11:20:00Z",
      "channel": "whatsapp",
      "manual_reply_mode": true,
      "last_escalated_at": "2026-01-15T11:10:00Z",
      "last_escalation_resolved_at": "2026-01-15T11:18:00Z",
      "assignee": {
        "id": 42,
        "name": "Stan Marsh",
        "email": "[e-mail]",
        "avatar_url": "https://app.zipchat.ai/rails/active_storage/blobs/redirect/.../avatar.png"
      },
      "share_url": "https://app.zipchat.ai/chats/1/conversations/12346",
      "lead": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 142,
    "total_pages": 3,
    "has_next_page": true
  }
}

The lead and assignee fields are null when not set. last_escalated_at is set when the conversation was escalated by the AI; last_escalation_resolved_at is set when an agent marked the escalation resolved.

---

Get Conversation

GET /chats/:chat_id/conversations/:id

Returns a single conversation with its messages.

Parameters

Parameter	Type	Default	Description
message_page	integer	1	Message page number
message_per_page	integer	100	Messages per page (max 200)
message_created_at_since	string	—	ISO 8601 timestamp. Only return messages created since this time.

Response

{
  "conversation": {
    "id": 12345,
    "created_at": "2026-01-15T10:30:00Z",
    "last_message_at": "2026-01-15T10:45:00Z",
    "channel": "web",
    "manual_reply_mode": false,
    "last_escalated_at": null,
    "last_escalation_resolved_at": null,
    "assignee": null,
    "share_url": "https://app.zipchat.ai/chats/1/conversations/12345",
    "lead": {
      "id": 100,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "email": "[e-mail]",
      "phone_number": "[phone]",
      "email_marketing_consent": true,
      "phone_marketing_consent": false,
      "shopify_customer_id": "7890123456",
      "additional_attributes": {},
      "created_at": "2026-01-15T10:31:00Z"
    },
    "messages": [
      {
        "id": 50001,
        "created_at": "2026-01-15T10:30:05Z",
        "role": "user",
        "message": "Do you have this in blue?",
        "count_as_reply": false,
        "manual_reply": false,
        "status": "sent",
        "rate": null,
        "sender_id": null
      },
      {
        "id": 50002,
        "created_at": "2026-01-15T10:30:08Z",
        "role": "assistant",
        "message": "Yes! The Classic Tee is available in blue.",
        "count_as_reply": true,
        "manual_reply": false,
        "status": "sent",
        "rate": "positive",
        "sender_id": null
      }
    ],
    "messages_pagination": {
      "page": 1,
      "per_page": 100,
      "total_count": 2,
      "total_pages": 1,
      "has_next_page": false
    }
  }
}

The show endpoint returns expanded lead details (including first_name, last_name, shopify_customer_id, and additional_attributes) compared to the list endpoint. The assignee, last_escalated_at, and last_escalation_resolved_at fields follow the same shape as on the list endpoint.

---

List Users

GET /chats/:chat_id/users

Returns the users (the chat owner and any chat participants) who can be assigned to a conversation on this chat.

Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	50	Items per page (max 100)

Response

{
  "users": [
    {
      "id": 42,
      "name": "Stan Marsh",
      "email": "[e-mail]",
      "avatar_url": "https://app.zipchat.ai/rails/active_storage/blobs/redirect/.../avatar.png"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1,
    "has_next_page": false
  }
}

avatar_url is null when the user has not uploaded an avatar.

---

Get User

GET /chats/:chat_id/users/:id

Returns a single user. Returns 404 if the user is not in the assignable set for this chat — the endpoint will never leak information about users from other chats.

Response

{
  "user": {
    "id": 42,
    "name": "Stan Marsh",
    "email": "[e-mail]",
    "avatar_url": null
  }
}

---

Update Conversation Assignment

PATCH /chats/:chat_id/conversations/:id/assignment

Takes a conversation over from the AI (manual mode) or hands it back to the AI. This is a single atomic operation: setting assignee_id to a user puts the conversation into manual mode; setting it to null puts it back into AI mode and unassigns.

Use GET /chats/:chat_id/users to discover valid assignee_id values.

Request body

{ "assignee_id": 42 }

Or, to hand back to the AI:

{ "assignee_id": null }

Response

{
  "conversation": {
    "id": 12345,
    "manual_reply_mode": true,
    "assignee": {
      "id": 42,
      "name": "Stan Marsh",
      "email": "[e-mail]",
      "avatar_url": null
    }
  }
}

Errors

Status	Error message	Cause
404 Not Found	Conversation not found	The conversation does not belong to this chat.
422 Unprocessable Entity	assignee_id is required (use null to assign to AI)	The body did not include assignee_id.
422 Unprocessable Entity	assignee_id is not an assignable user for this chat	The given user is not the chat owner or a participant.

---

Escalate or Resolve Conversation

PATCH /chats/:chat_id/conversations/:id/escalation

Updates the conversation's escalation state. It only updates the escalation timestamps — it does not send notifications or assign the conversation.

Request body

{ "resolved": false }

Field	Type	Description
resolved	boolean	Optional, defaults to false. When false (or omitted), escalates: sets last_escalated_at to now and clears last_escalation_resolved_at (so a previously resolved conversation is re-opened). When true, resolves: sets last_escalation_resolved_at to now and leaves last_escalated_at untouched.

Sending no body escalates the conversation.

Response

The same shape for both operations:

{
  "conversation": {
    "id": 12345,
    "currently_escalated": true,
    "last_escalated_at": "2026-01-15T11:10:00Z",
    "last_escalation_resolved_at": null
  }
}

currently_escalated is true when last_escalated_at is set and not yet resolved.

Errors

Status	Error message	Cause
404 Not Found	Conversation not found	The conversation does not belong to this chat.

---

Send Manual Message

POST /chats/:chat_id/conversations/:id/messages

Sends a manual reply from a human agent on a conversation that is currently in manual mode. The message is sent through whichever channel the conversation uses (web, email, WhatsApp, Instagram, Messenger).

You must take the conversation over first with PATCH /conversations/:id/assignment — sending while the conversation is still in AI mode returns 422.

Request body

{
  "message": "Hi! Happy to help with that.",
  "sender_id": 42
}

Field	Type	Description
message	string	The reply text. Required.
sender_id	integer	The user id that should be recorded as the sender. Must be a member of GET /chats/:chat_id/users. Required.

Response

{
  "message": {
    "id": 50003,
    "created_at": "2026-01-15T10:45:00Z",
    "role": "assistant",
    "message": "Hi! Happy to help with that.",
    "count_as_reply": false,
    "manual_reply": true,
    "status": "sent",
    "rate": null,
    "sender_id": 42
  }
}

Errors

Status	Error message	Cause
404 Not Found	Conversation not found	The conversation does not belong to this chat.
422 Unprocessable Entity	message is required	Empty or missing message.
422 Unprocessable Entity	sender_id is required	Missing sender_id.
422 Unprocessable Entity	sender_id is not an assignable user for this chat	Sender is not the chat owner or a participant.
422 Unprocessable Entity	Conversation is in AI mode; assign it to a user before sending a manual message	Call the assignment endpoint first.
422 Unprocessable Entity	Cannot send: customer last messaged more than 24 hours ago on a Meta channel	WhatsApp / Instagram / Messenger enforce a 24-hour reply window from Meta. Wait for the customer to message again.

---

Get Master Prompt

GET /chats/:chat_id/prompt

Returns the chat's current master prompt. Use this to read before modifying (e.g. to append to the existing prompt client-side).

Response

{
  "prompt": {
    "chat_id": 1,
    "master_prompt": "You are a helpful support assistant for Acme Co.",
    "master_prompt_max_length": 10000
  }
}

---

Update Master Prompt

PATCH /chats/:chat_id/prompt

Replaces the chat's master prompt (the bot's core behavior instructions).

Request body

{ "master_prompt": "You are a helpful support assistant for Acme Co." }

Field	Type	Description
master_prompt	string	The new master prompt. Required. Leading/trailing whitespace is stripped. Must not exceed the chat's configured maximum length.

Response

{
  "prompt": {
    "chat_id": 1,
    "master_prompt": "You are a helpful support assistant for Acme Co.",
    "master_prompt_max_length": 10000
  }
}

Errors

Status	Error message	Cause
403 Forbidden	Your role does not allow configuration changes	User token belongs to a read-only (member-role) user.
422 Unprocessable Entity	master_prompt is required	The body did not include master_prompt.
422 Unprocessable Entity	master_prompt cannot be blank	The value was null, empty, or whitespace-only. Blank values are rejected rather than silently erasing the prompt.
422 Unprocessable Entity	Master prompt must be at most N characters long	The prompt exceeded master_prompt_max_length.

---

Custom Tools (Skills)

Custom tools (labeled "skills" in the dashboard) are per-chat actions the AI can invoke.

List

GET /chats/:chat_id/custom_tools

Paginated (page, per_page, max 100).

{
  "custom_tools": [
    {
      "id": 12,
      "name": "Order lookup",
      "instructions": "Fetch orders from the API",
      "active": true,
      "channels": ["all channels"],
      "icon_id": null,
      "custom_tool_template_id": null,
      "variable_ids": [5, 7],
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total_count": 1, "total_pages": 1, "has_next_page": false }
}

Create

POST /chats/:chat_id/custom_tools

{
  "custom_tool": {
    "name": "Order lookup",
    "instructions": "Fetch orders from the API",
    "channels": ["all channels"],
    "active": true,
    "variable_ids": [5, 7]
  }
}

Field	Type	Description
name	string	Required, max 255 chars.
instructions	string	Required, max 10000 chars.
channels	array	Channels the tool is active on. When omitted, defaults to the template's install channels if custom_tool_template_id is given, otherwise ["all channels"].
active	boolean	Optional, defaults to true.
variable_ids	array	Optional. IDs of existing pool variables to attach to this tool. Must be an array of ids (422 otherwise).

Returns 201 with the serialized custom tool. Validation failures return 422 with an error message — including an unknown icon_id or custom_tool_template_id (icon_id does not exist / custom_tool_template_id does not exist).

Update

PATCH /chats/:chat_id/custom_tools/:id

Same body shape as create (all fields optional; custom_tool_template_id is create-only and ignored here). variable_ids, when present, is the full desired set of attached variables: missing ones are attached and absent ones detached (detaching only removes the link — the pooled variable itself is untouched). Omit the key to leave attachments unchanged. Returns 200, or 404 if the tool does not belong to this chat.

Delete

DELETE /chats/:chat_id/custom_tools/:id

Returns 204 No Content, or 404 if the tool does not belong to this chat.

---

Variables

Variables are a per-chat pool of secrets (e.g. API keys) that custom tools reference. Values are write-only — they are encrypted at rest and never returned by the API; responses expose only a has_value flag.

List

GET /chats/:chat_id/variables

Paginated (page, per_page, max 100).

{
  "variables": [
    {
      "id": 5,
      "name": "API_KEY",
      "kind": "user",
      "has_value": true,
      "usage_count": 2,
      "custom_tool_ids": [12],
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total_count": 1, "total_pages": 1, "has_next_page": false }
}

kind is user for normal variables or managed_shopify for the reserved, auto-managed SHOPIFY_API_KEY.

Create

POST /chats/:chat_id/variables

{
  "skill_variable": {
    "name": "API_KEY",
    "value": "sk_live_...",
    "custom_tool_ids": [12]
  }
}

Field	Type	Description
name	string	Required. Uppercase letters, digits, and underscores only (e.g. API_KEY). Unique per chat.
value	string	Required. Stored encrypted; never returned.
custom_tool_ids	array	Optional. Custom tools to attach this variable to.

Returns 201. Validation failures (bad name format, duplicate, reserved name) return 422.

Update

PATCH /chats/:chat_id/variables/:id

Updates the value only. The change propagates to every custom tool the variable is attached to.

{ "skill_variable": { "value": "sk_live_new..." } }

Returns 200. Returns 422 if value is blank, 404 if the variable is not on this chat, or 422 when targeting the managed SHOPIFY_API_KEY (it cannot be edited via the API).

Delete

DELETE /chats/:chat_id/variables/:id

Returns 204 No Content. Returns 404 if the variable is not on this chat, or 422 for the managed SHOPIFY_API_KEY (it cannot be deleted).

Rate Limiting

The API allows 120 requests per 60-second window per credential (per chat integration for chat tokens, per user for user tokens).

Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window (120)
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

When the limit is exceeded, the API returns 429 Too Many Requests.

Error Codes

Status	Description
401 Unauthorized	Missing or invalid API key
403 Forbidden	User token's role does not allow configuration changes (prompt, custom tools, variables)
404 Not Found	Conversation, user, custom tool, or variable not found
422 Unprocessable Entity	Invalid parameter (e.g., malformed timestamp, missing field, ineligible assignee)
429 Too Many Requests	Rate limit exceeded

Examples

Discover your chats with a user token

curl -H "Authorization: Bearer zcu-your_user_token" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats"

Read, then append to the master prompt

# 1. Read the current prompt
curl -H "Authorization: Bearer zcu-your_user_token" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/prompt"

# 2. Send back the full prompt with your addition appended
curl -X PATCH \
  -H "Authorization: Bearer zcu-your_user_token" \
  -H "Content-Type: application/json" \
  -d '{"master_prompt": "<existing prompt>\n\nAlways mention our 30-day return policy."}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/prompt"

Create a custom tool with a secret variable

# 1. Create the variable (value is write-only; it is never returned)
curl -X POST \
  -H "Authorization: Bearer zcu-your_user_token" \
  -H "Content-Type: application/json" \
  -d '{"skill_variable": {"name": "ORDERS_API_KEY", "value": "sk_live_..."}}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/variables"

# 2. Create the tool and attach the variable (use the id from step 1)
curl -X POST \
  -H "Authorization: Bearer zcu-your_user_token" \
  -H "Content-Type: application/json" \
  -d '{"custom_tool": {"name": "Order lookup", "instructions": "Call GET https://api.example.com/orders/{id} with the ORDERS_API_KEY header...", "variable_ids": [5]}}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/custom_tools"

Copy a custom tool to another chat

# 1. List tools on the source chat, pick the one to copy
curl -H "Authorization: Bearer zcu-your_user_token" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/custom_tools"

# 2. POST its name/instructions/channels to the destination chat
curl -X POST \
  -H "Authorization: Bearer zcu-your_user_token" \
  -H "Content-Type: application/json" \
  -d '{"custom_tool": {"name": "Order lookup", "instructions": "...", "channels": ["all channels"]}}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/2/custom_tools"

Fetch the latest conversations

curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations"

Fetch conversations updated in the last hour

curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations?last_message_at_since=2026-01-15T09:30:00Z"

Fetch a single conversation with messages

curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345"

Paginate through messages

curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345?message_page=2&message_per_page=50"

Take over a conversation, reply, and hand it back to the AI

# 1. Take the conversation over and assign it to user 42
curl -X PATCH \
  -H "Authorization: Bearer zc-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": 42}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345/assignment"

# 2. Send a manual reply on behalf of user 42
curl -X POST \
  -H "Authorization: Bearer zc-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hi! Happy to help.", "sender_id": 42}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345/messages"

# 3. Hand the conversation back to the AI
curl -X PATCH \
  -H "Authorization: Bearer zc-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": null}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345/assignment"

Escalate, then resolve a conversation

# Escalate (no body needed)
curl -X PATCH \
  -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345/escalation"

# Resolve the escalation
curl -X PATCH \
  -H "Authorization: Bearer zc-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}' \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345/escalation"