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
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
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
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
id
✅
string
A UUID string identifying this Inbox.
Request Body
Request Parameters
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
id
✅
string
A UUID string identifying this Inbox.
Request Body
Request Parameters
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
id
✅
string
A UUID string identifying this Inbox.
Code Examples
Response Body
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
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/
Parameters
inboxPk
✅
string
Request Body
Request Parameters
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
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
id
✅
string
A UUID string identifying this Inbox Webhook.
inboxPk
✅
string
Request Body
Request Parameters
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
id
✅
string
A UUID string identifying this Inbox Webhook.
inboxPk
✅
string
Request Body
Request Parameters
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
id
✅
string
A UUID string identifying this Inbox Webhook.
inboxPk
✅
string
Code Examples
Response Body
204
No response body
4XX
Error response; X-Error-Code carries its code (see "Error codes").
Last updated
Was this helpful?