For the complete documentation index, see llms.txt. This page is also available as Markdown.

Inboxes

An inbox is the unit to which conversations belong and where Webhooks are configured. Each inbox can have multiple Webhooks that send notifications to your system when a user message arrives (incoming) or an Agent replies (outgoing). Web Chat inboxes also have Web Chat endpoints. For configuration instructions and payload formats, see Webhook in the technical manual.

List Chat Platforms

GET /api/v1/inboxes/

Parameters

Parameter Name
Required
Type
Description

accessType

❌

string

Filter by access type

channelType

❌

string

Filter by channel type

chatbot

❌

string

Filter by chatbot ID

excludeTeam

❌

boolean

Leave out the chat platforms of teams' entry assistants, which the team's role grants decide.

excludeVoice

❌

boolean

Leave out every voice agent inbox (inbox settings list).

includeVoice

❌

boolean

With chatbot: also list the inboxes of the voice agents answered by it (role page, chat platform list).

isActive

❌

boolean

Filter by active status

ordering

❌

string

Which field to use when ordering the results.

page

❌

integer

A page number within the paginated result set.

pageSize

❌

integer

Number of results to return per page.

pagination

❌

string

Whether to paginate (true/false). When set to false, a simplified data format is returned

query

❌

string

source

❌

string

`self_built`: self_built ; `built_in`: built_in ; `all`: all;

Code Examples

Response Body

Status Code: 200 - List of chat platforms

Response Schema Example

Example Response Values

Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").


Create Chat Platform

POST /api/v1/inboxes/

Request Body

Request Parameters

Field
Type
Required
Description

name

string

Yes

channelType

string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber)

Yes

line: LINE ; telegram: Telegram ; teams: Teams ; web: Web ; messenger: Messenger ; instagram: Instagram ; email: Email ; whatsapp: WhatsApp ; slack: Slack ; team_plus: Team+ ; `lin...

unreadConversationsCount

integer

No

signAuth

object (with 9 properties: id, signSource, signParams...)

No

signAuth.signSource

string (uuid)

Yes

signAuth.signParams

object

Yes

signAuth.signParams.keycloak

object (with 3 properties: clientId, url, realm)

Yes

signAuth.signParams.keycloak.clientId

string

Yes

signAuth.signParams.keycloak.url

string

Yes

signAuth.signParams.keycloak.realm

string

Yes

signAuth.signParams.line

object (with 1 property: liffId)

Yes

signAuth.signParams.line.liffId

string

Yes

signAuth.signParams.ad

object (with 1 property: saml)

Yes

signAuth.signParams.ad.saml

string

Yes

signAuth.signParams.google

object (with 1 property: enabled)

No

signAuth.signParams.google.enabled

boolean

Yes

signAuth.sourceIdAccessEnabled

boolean

No

When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.

signAuth.sourceIdVerifyMode

object

No

"Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...

signAuth.sourceIdSignatureTtlMinutes

object

No

How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. 1: 1 ; 5: 5 ; 15: 15;

signAuth.keycloakTokenPassthrough

boolean

No

When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...

signAuth.keycloakTokenPassthroughAllowedHosts

array[string]

No

Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to

enableAnalysis

boolean

No

Request Schema Example

Example Request Values

Code Examples

Response Body

Status Code: 201

Response Schema Example

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Retrieve a Specific Inbox

GET /api/v1/inboxes/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox.

Code Examples

Response Body

Status code: 200

Example Response Schema

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Update an Inbox

PUT /api/v1/inboxes/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox.

Request Body

Request Parameters

Field
Type
Required
Description

name

string

Yes

channelType

string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber)

Yes

line: LINE ; telegram: Telegram ; teams: Teams ; web: Web ; messenger: Messenger ; instagram: Instagram ; email: Email ; whatsapp: WhatsApp ; slack: Slack ; team_plus: Team+ ; `lin...

unreadConversationsCount

integer

No

signAuth

object (with 9 properties: id, signSource, signParams...)

No

signAuth.signSource

string (uuid)

Yes

signAuth.signParams

object

Yes

signAuth.signParams.keycloak

object (with 3 properties: clientId, url, realm)

Yes

signAuth.signParams.keycloak.clientId

string

Yes

signAuth.signParams.keycloak.url

string

Yes

signAuth.signParams.keycloak.realm

string

Yes

signAuth.signParams.line

object (with 1 properties: liffId)

Yes

signAuth.signParams.line.liffId

string

Yes

signAuth.signParams.ad

object (with 1 properties: saml)

Yes

signAuth.signParams.ad.saml

string

Yes

signAuth.signParams.google

object (with 1 properties: enabled)

No

signAuth.signParams.google.enabled

boolean

Yes

signAuth.sourceIdAccessEnabled

boolean

No

When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.

signAuth.sourceIdVerifyMode

object

No

"Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...

signAuth.sourceIdSignatureTtlMinutes

object

No

How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. 1: 1 ; 5: 5 ; 15: 15;

signAuth.keycloakTokenPassthrough

boolean

No

When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...

signAuth.keycloakTokenPassthroughAllowedHosts

array[string]

No

Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to

enableAnalysis

boolean

No

Example Request Schema

Example Request Values

Code Examples

Response

Status code: 200

Response Schema Example

Response Example Values

Status code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").


Partially Update Inbox

PATCH /api/v1/inboxes/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox.

Request Body

Request Parameters

Field
Type
Required
Description

groups

array[IdName]

No

List of groups that can access this inbox

channelType

string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber)

No

line: LINE ; telegram: Telegram ; teams: Teams ; web: Web ; messenger: Messenger ; instagram: Instagram ; email: Email ; whatsapp: WhatsApp ; slack: Slack ; team_plus: Team+ ; `lin...

name

string

No

autoReplySchedules

array[AutoReplySchedule]

No

channel

object

No

organization

string (uuid)

No

signAuth

object (10 properties: id, signSource, signParams...)

No

signAuth.signSource

string (uuid)

Yes

signAuth.signParams

object

Yes

signAuth.signParams.keycloak

object (3 properties: clientId, url, realm)

Yes

signAuth.signParams.keycloak.clientId

string

Yes

signAuth.signParams.keycloak.url

string

Yes

signAuth.signParams.keycloak.realm

string

Yes

signAuth.signParams.line

object (1 properties: liffId)

Yes

signAuth.signParams.line.liffId

string

Yes

signAuth.signParams.ad

object (1 properties: saml)

Yes

signAuth.signParams.ad.saml

string

Yes

signAuth.signParams.google

object (1 properties: enabled)

No

signAuth.signParams.google.enabled

boolean

Yes

signAuth.sourceIdAccessEnabled

boolean

No

When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.

signAuth.sourceIdVerifyMode

object

No

"Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...

signAuth.sourceIdSignatureTtlMinutes

object

No

How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. 1: 1 ; 5: 5 ; 15: 15;

signAuth.keycloakTokenPassthrough

boolean

No

When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...

signAuth.keycloakTokenPassthroughAllowedHosts

array[string]

No

Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to

enableTimeAwareResponse

boolean

No

Enable time aware responses for this inbox

defaultTimezone

string

No

Default timezone for this inbox (e.g., Asia/Taipei, America/New_York)

enableSenderNameAwareResponse

boolean

No

Enable sender name aware responses for this inbox

enableGpsAwareResponse

boolean

No

Enable GPS aware responses for this inbox

gpsRequestTiming

object

No

Web chat only. "on_open" asks the browser for the location as soon as the chat opens (current behavior); "on_demand" asks only when the AI requests it through an ask_user_question question carrying ex...

enableAiLineSticker

boolean

No

LINE inboxes only. When on, the AI may attach one LINE official sticker to a reply (from the global LINE AI sticker list).

enableOcr

boolean

No

Retired: attachments pick their parser by content detection (image-heavy files go to the Vision Parser, billed by token; scanned and text files to the MaiAgent Parser, scanned pages billed as OCR) and...

enableAgentAttachmentDecision

boolean

No

Kill switch for AGENT-mode attachment handling. When False (default), AGENT-mode chatbots skip auto-embedding on upload and let the agent handle attachments at runtime via ParseAttachmentContentTool /...

enableStreamMessage

boolean

No

enableHumanHandoff

boolean

No

handoffPrompt

string

No

handoffLlm

string (uuid)

No

handoffContextMessageLimit

integer

No

handoffMessage

string

No

queuingMessage

string

No

assignedMessage

string

No

enablePendingReplyMessage

boolean

No

Send a placeholder message to the user while the AI is processing.

pendingReplyMessage

string

No

pendingReplyInitialDelaySeconds

integer

No

Delay before sending the first pending reply, so a fast AI response can pre-empt it.

pendingReplyIntervalSeconds

integer

No

Interval to repeat the pending reply while the AI is still processing.

enablePendingReplyCleanup

boolean

No

Delete pending reply messages after the AI reply is sent. Only effective on platforms that support message deletion (Teams, Telegram, Slack).

enableAnalysis

boolean

No

analysisLlm

string (uuid)

No

analysisPrompt

string

No

analysisContextMessageLimit

integer

No

analysisGenerateSummary

boolean

No

When on, conversation analysis writes the conversation summary (editable, with revisions); inbox auto split brings it to the next conversation

analysisApplyTags

boolean

No

When on, conversation analysis picks the conversation tags from the inbox tags

enableServiceHours

boolean

No

serviceHoursTimezone

string

No

offlineBehavior

string (enum: show_message, leave_message)

No

show_message: Show Message ; leave_message: Leave Message;

offlineMessage

string

No

serviceHoursSchedules

array[ServiceHoursSchedule]

No

dispatchMode

object

No

Auto dispatch assigns transferred conversations to an agent automatically. Claim (handover) leaves them unassigned for online agents to pick up themselves; timeout reassignment does not apply and the ...

assignmentRoutingModel

string (enum: round_robin, least_active)

No

round_robin: Round Robin ; least_active: Least Active;

assignmentMaxConcurrent

integer

No

assignmentQueueTimeout

integer

No

Queue timeout in seconds

queueTimeoutMessage

string

No

maxQueueSize

integer

No

queueFullMessage

string

No

assignmentTargetMembers

array[string]

No

enableTagRouting

boolean

No

enableReassignOnTimeout

boolean

No

When on, a queued or assigned-but-unanswered conversation that times out is reassigned to the next available agent (skipping already-tried agents) instead of returning straight to the AI; it only retu...

enableQueueReminder

boolean

No

Reply with a throttled waiting reminder when the contact sends messages while queued.

queueReminderMessage

string

No

queueReminderCooldown

integer

No

Minimum seconds between queue reminders in one conversation

enableQueueCancel

boolean

No

Allow the contact to cancel a queued handoff and return to the AI by themselves.

queueCancelButtonText

string

No

Label of the cancel quick-reply button. Its text also counts as a cancel keyword, so tapping the button always cancels even when the keyword list changes.

queueCancelKeywords

object

No

Messages matching one of these exactly (after stripping surrounding whitespace) cancel the queued handoff. Empty means no keyword matching (the cancel button text still matches); the serializer requir...

queueCancelMessage

string

No

Sent to the contact right after they cancel the queued handoff.

enableIdleAutoResolve

boolean

No

Resolve a conversation served by a human agent once the agent replied last and the contact has not answered for the idle minutes. Frees the agent slot; queued conversations and ones where the contact ...

idleAutoResolveMinutes

integer

No

Minutes the contact may stay silent after the last agent reply before auto resolve

idleAutoResolveMessage

string

No

Sent to the contact when the conversation is auto resolved; blank sends nothing. LINE delivers it as a push message (counts toward the LINE message quota); Messenger / Instagram / WhatsApp skip it onc...

enableAgentReplyTimeout

boolean

No

When on, a conversation served by a human agent returns to the AI once a contact message has gone unanswered by any agent for the configured seconds; the AI then answers the last unanswered message. A...

agentReplyTimeout

integer

No

Seconds (60-86400) a contact message may go unanswered by a human agent before the AI takes over

agentReplyTimeoutMessage

string

No

Sent to the contact when the conversation returns to the AI; leave empty to send none.

enableReturnToPreviousAssignee

boolean

No

When on, a resolved conversation the contact writes to again within the configured hours reopens assigned to the agent who held it instead of to the AI. It still reopens to the AI when that agent is o...

returnToPreviousAssigneeHours

integer

No

Hours (1-720), counted from when the conversation was resolved, during which a returning contact goes back to the agent who held it

enableAutoSplit

boolean

No

When on, a one-to-one contact writing again after the conversation was resolved or went idle for the configured time starts a new conversation instead of continuing the old one. Web inboxes and group ...

autoSplitOnResolve

boolean

No

Split when the latest conversation was resolved more than the configured minutes ago

autoSplitResolveMinutes

integer

No

Minutes (0-10080) after the latest resolve; 0 splits on the next contact message

autoSplitOnIdle

boolean

No

Split when the last message of the latest conversation is older than the configured hours, unless a human agent is serving it or it is queued

autoSplitIdleHours

integer

No

Hours (1-720) since the last message of the latest conversation

enableContinuationSummary

boolean

No

When on, a conversation started by auto split gives its AI the previous conversations' analysis summaries; a previous conversation without a current summary gets one from conversation analysis (one bi...

continuationSummaryCount

integer

No

How many previous conversations (1-3) a new conversation looks back at for summaries

copilotEnabled

boolean

No

copilotTriggerMode

string (enum: manual, every_incoming)

No

manual: Manual ; every_incoming: Every Incoming;

quotaExceededMessage

string

No

Custom message sent to the visitor when the inbox credit quota is exhausted. Used as the fallback when quota_exceeded_message_by_locale has no match for the conversation locale. Empty means the syst...

quotaExceededMessageByLocale

object

No

Locale-keyed quota-exceeded messages. A dict mapping normalized locale codes from CHAT_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to `q...

creditSuspendedMessage

string

No

Custom message sent to the visitor when the AI auto-reply is suspended because the organization has run out of credits or has no active plan. Used as the fallback when `credit_suspended_message_by_loc...

creditSuspendedMessageByLocale

object

No

Locale-keyed credit-suspended messages. A dict mapping normalized locale codes from CHAT_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to ...

voiceEntry

object (8 properties: isActive, voiceUrl, usesGreeting...)

No

A voice inbox's entry switch, voice link and greetings (decision 50); null for other inboxes. Rendered by retrieve and update only.

voiceEntry.isActive

boolean

No

The voice entry switch (the VOICE web chat); off refuses new calls only.

voiceEntry.greetings

array[string]

No

The voice agent's greetings, one picked at random per call.

voiceEntry.greetingsByLocale

object

No

The voice agent's greetings by locale.

Request Schema Example

Example Request Values

Code Examples

Response Body

Status code: 200

Example Response Schema

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Delete Inbox

DELETE /api/v1/inboxes/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox.

Code Examples

Response Body

Status code
Description

204

No response body

4XX

Error response; X-Error-Code carries its code (see "Error codes").


List Webhooks for an Inbox

GET /api/v1/inboxes/{inboxPk}/webhooks/

Parameters

Parameter
Required
Type
Description

inboxPk

✅

string

page

❌

integer

A page number within the paginated result set.

pageSize

❌

integer

Number of results to return per page.

Code Examples

Response Body

Status code: 200

Example Response Schema

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Create Webhook

POST /api/v1/inboxes/{inboxPk}/webhooks/

direction is either incoming (triggered when a user message arrives) or outgoing (triggered when the Agent replies). Set template_preset to maiagent_standard to use the MaiAgent standard payload.

Parameters

Parameter
Required
Type
Description

inboxPk

✅

string

Request Body

Request Parameters

Field
Type
Required
Description

name

string

Yes

Webhook configuration name for identification

direction

object

Yes

When to trigger: incoming (user messages) or outgoing (bot replies) incoming: Incoming ; outgoing: Outgoing ; receive: Receive;

isEnabled

boolean

No

url

string (uri)

No

method

object

No

headers

object

No

Custom HTTP headers as JSON object

templatePreset

string (enum: maiagent_standard, genesys_cloud, custom)

No

maiagent_standard: MaiAgent Standard ; genesys_cloud: Genesys Cloud ; custom: Custom;

customTemplate

string

No

Jinja2 template for custom payload format. Required when template_preset is "custom".

secretToken

string

No

Secret token for webhook signature verification

payloadPreset

object

No

Preset for parsing incoming webhook payloads (used with direction=receive) genesys_cloud: Genesys Cloud;

Example Request Schema

Example Request Values

Code Examples

Response Body

Status code: 201

Example Response Schema

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Retrieve a Webhook

GET /api/v1/inboxes/{inboxPk}/webhooks/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox Webhook.

inboxPk

✅

string

Code Examples

Response Body

Status code: 200

Example Response Schema

Example Response Values

Status code: 4XX - Error response; the error code is returned in the X-Error-Code header (see "Error codes").


Update Webhook

PUT /api/v1/inboxes/{inboxPk}/webhooks/{id}/

Parameters

Parameter
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox Webhook.

inboxPk

✅

string

Request Body

Request Parameters

Field
Type
Required
Description

name

string

Yes

Webhook configuration name for identification

direction

object

Yes

When to trigger: incoming (user messages) or outgoing (bot replies) incoming: Incoming ; outgoing: Outgoing ; receive: Receive;

isEnabled

boolean

No

url

string (uri)

No

method

object

No

headers

object

No

Custom HTTP headers as JSON object

templatePreset

string (enum: maiagent_standard, genesys_cloud, custom)

No

maiagent_standard: MaiAgent Standard ; genesys_cloud: Genesys Cloud ; custom: Custom;

customTemplate

string

No

Jinja2 template for custom payload format. Required when template_preset is "custom".

secretToken

string

No

Secret token for webhook signature verification

payloadPreset

object

No

Preset for parsing incoming webhook payloads (used with direction=receive) genesys_cloud: Genesys Cloud;

Example Request Schema

Example Request Values

Code Examples

Response Body

Status Code: 200

Example Response Schema

Example Response Values

Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").


Partially Update Webhook

PATCH /api/v1/inboxes/{inboxPk}/webhooks/{id}/

Parameters

Parameter Name
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox Webhook.

inboxPk

✅

string

Request Body

Request Parameters

Field
Type
Required
Description

name

string

No

Webhook configuration name for identification

direction

object

No

When to trigger: incoming (user messages) or outgoing (bot replies) incoming: Incoming ; outgoing: Outgoing ; receive: Receive;

isEnabled

boolean

No

url

string (uri)

No

method

object

No

headers

object

No

Custom HTTP headers as JSON object

templatePreset

string (enum: maiagent_standard, genesys_cloud, custom)

No

maiagent_standard: MaiAgent Standard ; genesys_cloud: Genesys Cloud ; custom: Custom;

customTemplate

string

No

Jinja2 template for custom payload format. Required when template_preset is "custom".

secretToken

string

No

Secret token for webhook signature verification

payloadPreset

object

No

Preset for parsing incoming webhook payloads (used with direction=receive) genesys_cloud: Genesys Cloud;

Example Request Schema

Example Request Values

Code Examples

Response Body

Status Code: 200

Example Response Schema

Example Response Values

Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").


Delete Webhook

DELETE /api/v1/inboxes/{inboxPk}/webhooks/{id}/

Parameters

Parameter Name
Required
Type
Description

id

✅

string

A UUID string identifying this Inbox Webhook.

inboxPk

✅

string

Code Examples

Response Body

Status Code
Description

204

No response body

4XX

Error response; X-Error-Code carries its code (see "Error codes").


Last updated

Was this helpful?