A conversation is a unique thread of messages. It can appear in one or more inboxes (eg: if you receive an email on contact@ where support@ is CC'd).

Even if a conversation's messages has multiple recipients, the conversation resource will always have only one. The main recipient of a conversation can change over the time depending on each message received. It will generally be the sender of the last incoming message.

Creating a new conversation

Conversations cannot be empty. That is, they need to contain a message, discussion, or draft to be created. As such, there are three main ways to create a new conversation via the Core API:

Create a new message — this option creates a new message in a channel, thereby creating the parent conversation object to the message. The conversation created supports both messages and comments (discussions).
Create a new discussion conversation — this option creates a new comment (discussion) in Front, thereby creating the parent conversation object to the discussion. This conversation type is limited to comments (discussions) and does not support messages.
Create a new draft — this option creates a new message draft in Front, thereby creating the parent conversation object to the draft.

On a related note, you can import messages into Front. The Import message endpoint allows you to import messages that have already taken place in external systems and add them to Front inboxes for historical reasons, threading these messages into a conversation of your choice.

If you create an application channel or custom channel, you can sync or receive messages into those channels.

Opening a conversation in Front

To open a conversation in Front you need to open the URL https://app.frontapp.com/open/{conversation_id}

You can obtain the conversation ID from the self property in the _links object of the conversation object (example value cnv_55c8c149 obtained from https://api2.frontapp.com/conversations/cnv_55c8c149). After extracting the ID, append it to the https://app.frontapp.com/open/ URL.

Search for Conversations

To learn how to search for conversations via the API, refer to our Search topic.

Query string parameter `q`

To learn how to use the query string parameter q to filter conversations, refer to our Query object 'q' topic.

Example Conversation Object

{
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
    "related": {
      "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
      "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
      "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
      "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
      "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes",
      "last_message": "https://api2.frontapp.com/messages/msg_55c8c149"
    }
  },
  "id": "cnv_55c8c149",
  "subject": "You broke my heart, Hubert.",
  "status": "archived",
  "status_id": "sts_5x",
  "status_category": "resolved",
  "ticket_ids": [
    "TICKET-1"
  ],
  "assignee": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true,
    "is_blocked": false
  },
  "recipient": {
    "_links": {
      "related": {
        "contact": "https://api2.frontapp.com/contacts/crd_55c8c149"
      }
    },
    "handle": "calculon@momsbot.com",
    "role": "to"
  },
  "tags": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/tags/tag_55c8c149",
        "related": {
          "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations",
          "owner": "https://api2.frontapp.com/teams/tim_55c8c149",
          "children": "https://api2.frontapp.com/tags/tag_55c8c149/children"
        }
      },
      "id": "tag_55c8c149",
      "name": "Robots",
      "highlight": "blue",
      "is_private": false,
      "created_at": 0,
      "updated_at": 0
    }
  ],
  "created_at": 1453770984.123,
  "is_private": false
}