Sign in

v1

latestOpenAPI 3.0.02026-07-26254134307.1 KB
Conversations

Create discussion/task conversation

Create a new conversation of type discussion or task. Both types only support comments. If you want to create a conversation that supports messages, use the Create message endpoint. If you want to add a comment to an existing conversation, use the Add comment endpoint.

Required scope: conversations:write

post/conversations

Request body

type'discussion' | 'task' required

Conversation type

inbox_idstring

Inbox ID for the conversation. Either inbox_id OR teammate_ids must be provided (not both).

teammate_idsstring[]

Teammates to add to the conversation. Either inbox_id OR teammate_ids must be provided (not both).

subjectstring required

Subject of the conversation. Used as the title for tasks.

descriptionstring

Description of the task. Only allowed when type is task.

due_atnumber

Unix timestamp in seconds when the task is due. Must be in the future and within 50 years. Only allowed when type is task.

custom_fieldsCustomFieldParameter

An object whose key is the name property defined for the custom field in the Front UI. The value of the key must use the same type specified for the custom field, as described in https://dev.frontapp.com/reference/custom-fields

Example request

{
  "custom_fields": {
    "city": "London, UK",
    "isVIP": true,
    "renewal_date": 1525417200,
    "sla_time": 90,
    "owner": "leela@planet-express.com",
    "replyTo": "inb_55c8c149",
    "Job Title": "firefighter"
  }
}

Response

A conversation

idstring required

Unique identifier of the conversation

type'conversation' | 'discussion' | 'task' required

Type of the conversation

subjectstring required

Subject of the message for email message

status'archived' | 'unassigned' | 'deleted' | 'assigned' required

Status of the conversation

status_idstring

Unique identifier of the conversation status category, only present if ticketing is enabled

status_category'open' | 'waiting' | 'resolved'

Status category of the conversation

ticket_idsstring[] required

List of ticket ids associated with the conversation

custom_fieldsCustomFieldParameter required

An object whose key is the name property defined for the custom field in the Front UI. The value of the key must use the same type specified for the custom field, as described in https://dev.frontapp.com/reference/custom-fields

created_atnumber

Timestamp at which the conversation was created.

updated_atnumber

Timestamp at which the conversation was last updated.

waiting_sincenumber

Timestamp of the oldest unreplied message.

is_privateboolean required

Whether or not the conversation is private

descriptionstring nullable

Description of the task. Only present on task conversations.

due_atnumber nullable

Unix timestamp in seconds when the task is due. Only present on task conversations.

Example response

{
  "_links": {
    "self": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q",
    "related": {
      "events": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/events",
      "followers": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/followers",
      "messages": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/messages",
      "comments": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/comments",
      "inboxes": "https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/inboxes",
      "last_message": "https://yourCompany.api.frontapp.com/messages/msg_1q15qmtq?referer=conversation"
    }
  },
  "id": "cnv_yo1kg5q",
  "type": "discussion",
  "subject": "How to prank Dwight Schrute",
  "status": "assigned",
  "status_id": "sts_5x",
  "status_category": "resolved",
  "ticket_ids": [
    "TICKET-1"
  ],
  "assignee": {
    "_links": {
      "self": "https://yourCompany.api.frontapp.com/teammates/tea_6r55a",
      "related": {
        "inboxes": "https://yourCompany.api.frontapp.com/teammates/tea_6r55a/inboxes",
        "conversations": "https://yourCompany.api.frontapp.com/teammates/tea_6r55a/conversations",
        "botSource": "https://yourCompany.api.frontapp.com/rules/rul_6r55a"
      }
    },
    "id": "tea_6r55a",
    "email": "michael.scott@dundermifflin.com",
    "username": "PrisonMike",
    "first_name": "Michael",
    "last_name": "Scott",
    "is_admin": true,
    "custom_fields": {
      "city": "London, UK",
      "isVIP": true,
      "renewal_date": 1525417200,
      "sla_time": 90,
      "owner": "leela@planet-express.com",
      "replyTo": "inb_55c8c149",
      "Job Title": "firefighter"
    }
  },
  "recipient": {
    "_links": {
      "related": {
        "contact": "https://yourCompany.api.frontapp.com/contacts/crd_2njtoem"
      }
    },
    "name": "Phyllis Lapin-Vance",
    "handle": "purpleboss@limitlesspaper.com",
    "role": "cc"
  },
  "tags": [
    {
      "_links": {
        "self": "https://yourCompany.api.frontapp.com/tags/tag_2oxhvy",
        "related": {
          "conversations": "https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/conversations",
          "owner": "https://yourCompany.api.frontapp.com/teammates/tea_6jydq",
          "parent_tag": "https://yourCompany.api.frontapp.com/tags/tag_3h07ym",
          "children": "https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/children"
        }
      },
      "id": "tag_2oxhvy",
      "name": "Warehouse task",
      "description": "Sitting on your biscuit, never having to risk it",
      "is_visible_in_conversation_lists": true,
      "created_at": 1682538996.583,
      "updated_at": 1699575875.186
    }
  ],
  "links": [
    {
      "_links": {
        "self": "https://yourCompany.api.frontapp.com/links/top_b2wpa"
      },
      "id": "top_b2wpa",
      "name": "JIRA-SCRAN-4567",
      "type": "app_2f76b9ac738de158",
      "external_url": "https://dundermifflin.atlassian.net/browse/PB-SCRAN-4567",
      "custom_fields": {
        "city": "London, UK",
        "isVIP": true,
        "renewal_date": 1525417200,
        "sla_time": 90,
        "owner": "leela@planet-express.com",
        "replyTo": "inb_55c8c149",
        "Job Title": "firefighter"
      }
    }
  ],
  "custom_fields": {
    "city": "London, UK",
    "isVIP": true,
    "renewal_date": 1525417200,
    "sla_time": 90,
    "owner": "leela@planet-express.com",
    "replyTo": "inb_55c8c149",
    "Job Title": "firefighter"
  },
  "created_at": 1701292649.333,
  "updated_at": 1701292649.333,
  "waiting_since": 1701292649.333,
  "is_private": true,
  "scheduled_reminders": [
    {
      "_links": {
        "related": {
          "owner": "https://yourCompany.api.frontapp.com/teammates/tea_6r55a"
        }
      },
      "created_at": 1701806790.536,
      "scheduled_at": 1701874800,
      "updated_at": 1701806790.536
    }
  ],
  "due_at": 1701292649.333,
  "metadata": {
    "external_conversation_ids": [
      "JS3949",
      "JS9403"
    ]
  }
}