Bento
View markdown

Chat

Use this API to triage Bento Chat support threads with your normal Bento API keys and site_uuid. Conversation IDs are Chat display IDs, the same numbers you see in Chat conversation URLs.

Call these endpoints from server-side code. Do not expose your Bento secret key in a browser or mobile app.
Your site must have Bento Chat enabled and connected.

Available Endpoints

MethodEndpointCopy
GET
/chat/conversations

List Conversations

Filter open threads by status, assignee, inbox, and search text.

GET
/chat/conversations/:id

Get Conversation

Fetch one conversation and its recent messages.

GET
/chat/conversations/by_email

List Conversations By Email

Fetch conversations for one contact email.

GET
/chat/inboxes

List Inboxes

List inboxes so you can pick an inbox_id.

POST
/chat/conversations/:id/messages

Send A Reply

Send a public reply in an existing conversation.

POST
/chat/messages

Start A Conversation

Start or continue a conversation for a contact email.

POST
/chat/conversations/:id/notes

Create A Private Note

Add a private note that is not sent to the customer.

POST
/chat/conversations/:id/status

Update Conversation Status

Resolve, reopen, or change conversation status.

The Conversation Model

Conversations are support threads in Bento Chat. Each record includes the contact, inbox, status, and latest activity. Message endpoints return the created message plus the conversation and contact summary.

Properties

  • Name
    idinteger
    Description

    Chat display ID for the conversation. Use this value in reply and note paths.

  • Name
    contactobject
    Description

    Contact summary with id, name, email, and phone_number.

  • Name
    inboxobject
    Description

    Inbox summary with id, name, and inbox_type.

  • Name
    assigneeobject|null
    Description

    Assigned agent when present. Contains id, name, and email.

  • Name
    statusstring
    Description

    Conversation status such as open, resolved, pending, or snoozed.

  • Name
    last_messagestring|null
    Description

    Content of the most recent message in the thread.

  • Name
    urlstring
    Description

    URL to open the conversation in Bento Chat.

GET/v1/chat/conversations

List Conversations

Returns conversations for the site. Filter by status, assignment, inbox, page, and message search text.

Optional Attributes

  • Name
    statusstring
    Description

    One of open, resolved, pending, snoozed, or all.

  • Name
    assignee_typestring
    Description

    One of me, unassigned, assigned, or all.

  • Name
    inbox_idinteger
    Description

    Limit results to one inbox.

  • Name
    qstring
    Description

    Search text matched against conversation messages.

  • Name
    pageinteger
    Description

    Page number for paginated results.



Response

Returns matching conversations and pagination metadata.

  • Name
    conversationsarray
    Description

    Conversation records for the current page.

  • Name
    meta.countinteger
    Description

    Number of conversations returned on this page.

  • Name
    meta.total_countinteger
    Description

    Total conversations that match the filters.

  • Name
    meta.pageinteger
    Description

    Current page number.

  • Name
    meta.per_pageinteger
    Description

    Page size used for the response.

GET/v1/chat/conversations/:id

Get Conversation

Returns one conversation and its most recent messages.



Response

Returns the conversation summary plus a messages array.

  • Name
    idinteger
    Description

    Chat display ID for the conversation.

  • Name
    messagesarray
    Description

    Recent messages in chronological order. Each item includes id, content, message_type, private, created_at, and sender.

GET/v1/chat/conversations/by_email

List Conversations By Email

Returns the contact and their conversations for one email address.

Required Attributes

  • Name
    contact_emailstring
    Description

    Email address of the contact to look up.



Response

Returns the contact summary and their conversations.

  • Name
    contactobject
    Description

    Contact summary with id, name, email, and phone_number.

  • Name
    conversationsarray
    Description

    Conversations for that contact, newest first.

GET/v1/chat/inboxes

List Inboxes

Returns inboxes for the site. Use an inbox id when starting a conversation.



Response

Returns the site inboxes.

  • Name
    successboolean
    Description

    true when the request succeeds.

  • Name
    inboxesarray
    Description

    Inbox records with id, name, channel_type, email, greeting fields, and timezone.

  • Name
    inboxes[].idinteger
    Description

    Inbox ID to pass as inbox_id when starting a conversation.

  • Name
    inboxes[].channel_typestring
    Description

    Channel class such as Channel::Email or Channel::WebWidget.

POST/v1/chat/conversations/:id/messages

Send A Reply

Sends a public reply in an existing conversation.

Required Attributes

  • Name
    message_contentstring
    Description

    Message body sent to the customer.



Response

Returns the created message with conversation and contact summaries.

  • Name
    successboolean
    Description

    true when the message is created.

  • Name
    messageobject
    Description

    Created message details, including id, content, message_type, private, created_at, and sender.

  • Name
    conversationobject
    Description

    Conversation summary with id and status.

  • Name
    contactobject
    Description

    Contact summary with id, name, and email.

POST/v1/chat/messages

Start A Conversation

Starts or continues a conversation for a contact email. Call List Inboxes first to get an inbox_id.

Required Attributes

  • Name
    inbox_idinteger|string
    Description

    Inbox ID from the list inboxes response.

  • Name
    contact_emailstring
    Description

    Email address of the contact.

  • Name
    message_contentstring
    Description

    Outgoing message body.

Optional Attributes

  • Name
    contact_namestring
    Description

    Name used when creating a new contact.

  • Name
    mail_subjectstring
    Description

    Subject line for email inbox conversations.



Response

Returns the created message with conversation and contact summaries.

  • Name
    successboolean
    Description

    true when the message is created.

  • Name
    messageobject
    Description

    Created message with id, content, and created_at.

  • Name
    conversation.idinteger
    Description

    Chat display ID for the new or existing conversation.

  • Name
    contactobject
    Description

    Contact summary with id, name, and email.

POST/v1/chat/conversations/:id/notes

Create A Private Note

Adds a private note to the conversation. Notes stay in the support thread and are not sent to the customer.

Required Attributes

  • Name
    contentstring
    Description

    Private note body.



Response

Returns the created private note with conversation and contact summaries.

  • Name
    successboolean
    Description

    true when the note is created.

  • Name
    message.privateboolean
    Description

    Always true for notes created through this endpoint.

  • Name
    message.contentstring
    Description

    Private note body.

POST/v1/chat/conversations/:id/status

Update Conversation Status

Updates the status of an existing conversation. Use resolved to close a support thread, or open to reopen one.

Required Attributes

  • Name
    statusstring
    Description

    One of open, resolved, pending, or snoozed.



Response

Returns the updated conversation summary.

  • Name
    successboolean
    Description

    true when the status is updated.

  • Name
    conversation.idinteger
    Description

    Chat display ID for the conversation.

  • Name
    conversation.statusstring
    Description

    Updated status such as resolved or open.