Skip to main content
A conversation is a messaging thread between your team and a customer. Conversations group messages, preserve context, and let your team manage ownership and status. Most conversations are tied to an inbox and a contact. When a message is sent or received, Heymarket associates it with the relevant conversation.

​
Conversation relationships

Conversations sit between contacts, messages, and inboxes:
  • Inbox - the sending or receiving channel your team uses.
  • Contact - the customer or person in the thread.
  • Messages - the individual inbound, outbound, email, MMS, private, or scheduled messages in the thread.
  • Members - team members who can access or act on the conversation.

​
Lifecycle

Conversations can be open or closed. Open conversations usually need attention. Closed conversations are resolved or no longer active. You can also mark conversations as read or unread, reassign them to another team member, and transfer them to another inbox.

​
Assignment and transfer

Use assignment when responsibility changes between team members inside the same inbox. Use transfer when a conversation should move to a different inbox, such as moving a sales conversation to support.

​
Listing conversations

Conversation lists are paginated with POST /v1/conversations. To retrieve older conversations, use the updated timestamp from the last conversation in the current response as the next date cursor. 
{
  "id": 0,
  "filters": {
    "inboxes": [42]
  },
  "date": "2026-04-12T15:30:00Z"
}
This lets you walk backward through conversation history without loading every conversation at once.

​
Finding the conversation to reply to

Inbound message webhook payloads include message and conversation data in event_data. Store the conversation ID from webhook events or message-history responses when your integration needs to reply in the same thread with chat_id.
Use filtering by inbox, closed status, and unread status to keep sync jobs small and focused.

Conversations reference

List, retrieve, open, close, reassign, and transfer conversations.

Messages

Learn how individual messages relate to conversations.

Webhook event reference

Review the event payload shape used for inbound replies.