A message is a resource which can be either received or sent via an inbox. Messages are grouped by conversations.

A message can be either inbound (received) or outbound (sent). You can know if a message has been received or sent thanks to the boolean is_inbound.

Each message has a type depending on the channel it has been sent with:

Type	Description
email	Email message
tweet	Message from Twitter
tweet_dm	Direct Message from Twitter
googleplay	GooglePlay message
sms	SMS message
whatsapp	WhatsApp message
smooch	Message from Smooch
facebook	Message from Facebook
intercom	Message from Intercom
call	Phone call
custom	Custom Message
front_chat	Front Chat message

📘
Twitter notice
In order to comply with Twitter's API Terms & Conditions, Twitter content is not distributed through Front API.
The fields blurb, body, text as well as recipients' handle are replaced by the string [REDACTED] for messages of type tweet or tweet_dm only.
For those messages, the payload includes the field metadata.external_id containing the ID of the original Tweet or Twitter Direct Message that can be used to fetch its content from the Twitter API directly.

Creating a new message

When you create a new message, you receive a 202 Accepted response that returns a message_uid. This response acknowledges your request to create a message in Front.

However, the message_uid is not the message_id that you must use to subsequently retrieve your message in API calls such Get message. The message_id is only generated once the message has been successfully created in Front.

Before you have the message_id, send the message_uid as a resource alias in API calls to check on the status of the message. If you receive a message without error codes, then the message has been successfully created in Front. You can then use the message_id from the returned message in subsequent API calls.

Note the message_uid field will be present on all message objects returned via the API or webhooks in addition to the message_id. Depending on your use-case, this may allow you to omit this lookup step, and wait to receive "new message" notifications via webhook subscriptions you may have configured, and reconcile the message ID / UID in your system at that point.

Opening a message in Front

To open a message in Front you need to open the URL https://app.frontapp.com/open/{message_id}. You can obtain the message ID from the self property in the _links object of the message object (example value msg_55c8c149 obtained from https://api2.frontapp.com/messages/msg_55c8c149). After extracting the ID, append it to the https://app.frontapp.com/open/ URL.

Note: You cannot open messages in a draft state. If you have a message in a draft state, use the ID of the parent conversation to open the conversation.

Example Message Object (Type: Email)

{
  "_links": {
    "self": "https://api2.frontapp.com/messages/msg_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
    }
  },
  "id": "msg_55c8c149",
  "type": "email",
  "is_inbound": true,
  "is_draft": false,
  "created_at": 1453770984.123,
  "blurb": "Anything less than immortality is a...",
  "author": {
    "_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
  },
  "recipients": [
    {
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/crd_55c8c149"
        }
      },
      "handle": "calculon@momsbot.com",
      "role": "to"
    }
  ],
  "body": "Anything less than immortality is a complete waste of time.",
  "text": "Anything less than immortality is a complete waste of time.",
  "attachments": [
    {
      "filename": "attachment.jpg",
      "url": "https://api2.frontapp.com/download/fil_55c8c149",
      "content_type": "image/jpeg",
      "size": 10000,
      "metadata": {
        "is_inline": true,
        "cid": "123456789"
      }
    }
  ],
  "metadata": {}
}

Example Message Object (Type: Chat Message)

{
    "_links": {
        "self": "https://sean-test-3-30.api.frontapp.com/messages/msg_18ia6pce",
        "related": {
            "conversation": "https://sean-test-3-30.api.frontapp.com/conversations/cnv_nyulbny",
            "message_seen": "https://sean-test-3-30.api.frontapp.com/messages/msg_18ia6pce/seen"
        }
    },
    "id": "msg_18ia6pce",
    "type": "front_chat",
    "is_inbound": true,
    "created_at": 1661471266.594,
    "blurb": "triple send!",
    "body": "<div>triple send!</div>",
    "text": "triple send!",
    "error_type": null,
    "version": null,
    "draft_mode": null,
    "metadata": {
        "chat_visitor_url": "http://0.0.0.0:8080/?fcsp=54e9d2f3900fe9ecbe057a97568bbdbe&pusher-key=a29c79de7a1a99077623&namespace=cmckee"
    },
    "author": null,
    "recipients": [
        {
            "_links": {
                "related": {
                    "contact": "https://sean-test-3-30.api.frontapp.com/contacts/crd_2kg0xla"
                }
            },
            "name": "Navy Nautilus",
            "handle": "3326f7d3-8e97-475d-8305-25815c3fc7f9",
            "role": "from"
        },
        {
            "_links": {
                "related": {
                    "contact": null
                }
            },
            "name": null,
            "handle": "5b9b1474ab2bc85b6ea6",
            "role": "to"
        }
    ],
    "attachments": [],
    "signature": null,
    "is_draft": false
}

Example Message Object (Type: Chatbot Transcript)

{
  "type": "front_chat",
  "path": "622b145724f15c9e276fef197ac0db4d-1-1689272472836-2861-1029",
  "headers": {
    "front_chat_conversation_id": "ff79c8fd-3858-4d30-8c8c-640f3351f7c1",
    "front_chat_page_url": "your_chat_url",
    "unverified": true,
    "decision_tree_responses": [
      {
        "timestamp": 1689272457222,
        "nodeId": "83b60472-e384-423f-acba-1865db396d07",
        "nodeData": {
          "type": "message",
          "message": "Hi! We're here to help!"
        },
        "responseData": {
          "nodeType": "message"
        }
      },
      {
        "timestamp": 1689272459545,
        "nodeId": "4e7531f5-b079-483c-8ab8-f43b983240e8",
        "nodeData": {
          "type": "multi_choice",
          "message": "hello",
          "options": [
            {
              "sourceHandle": "c10063a5-7767-4503-b7ef-cbd00ca67e93",
              "value": "1"
            },
            {
              "sourceHandle": "b7e9b29b-c13d-4ca2-8f72-7d18d9d7d3b8",
              "value": "2"
            }
          ]
        },
        "responseData": {
          "nodeType": "multi_choice",
          "response": "1",
          "responseLabel": "1"
        }
      },
      {
        "timestamp": 1689272465080,
        "nodeId": "b0f75d70-8206-441e-80f7-6f245ace468e",
        "nodeData": {
          "type": "prompt",
          "message": "woof woof"
        },
        "responseData": {
          "nodeType": "prompt",
          "response": "hallo thar sir!"
        }
      },
      {
        "timestamp": 1689272471716,
        "nodeId": "ea938ea9-c9d7-467a-83da-c33f05533a05",
        "nodeData": {
          "type": "custom_fields",
          "customFields": [
            {
              "customFieldId": -1,
              "fieldName": "Name",
              "fieldType": "string",
              "isRequired": false,
              "resourceType": "card"
            },
            {
              "customFieldId": -2,
              "fieldName": "Email",
              "fieldType": "email",
              "isRequired": false,
              "resourceType": "card"
            }
          ]
        },
        "responseData": {
          "nodeType": "custom_fields",
          "customFieldResponses": [
            {
              "customFieldId": -1,
              "fieldName": "Name",
              "fieldType": "string",
              "isRequired": false,
              "resourceType": "card",
              "response": "bruce"
            },
            {
              "customFieldId": -2,
              "fieldName": "Email",
              "fieldType": "email",
              "isRequired": false,
              "resourceType": "card",
              "response": "bruce@email.com"
            }
          ]
        }
      },
      {
        "timestamp": 1689272471717,
        "nodeId": "2",
        "nodeData": {
          "type": "end"
        },
        "responseData": {
          "nodeType": "end"
        }
      }
    ]
  },
  "subject": "",
  "text": "Hi! We're here to help!\n\nhello\n1\n\nwoof woof\nhallo thar sir!\n\nName: bruce\nEmail: bruce@email.com",
  "json": {
    "attachments": [],
    "sender": {
      "handle": "39fe4d09-a31f-4faa-b91e-ab13b62ad374",
      "customFields": {},
      "contact": {
        "name": "bruce",
        "email": "bruce@email.com"
      }
    },
    "id": "6086cd02-f486-495b-b29b-cea95cf6291a",
    "text": "",
    "front_chat_conversation_id": "ff79c8fd-3858-4d30-8c8c-640f3351f7c1",
    "date": 1689272471718,
    "is_inbound": false,
    "sent": true,
    "front_chat_page_url": "your_chat_url",
    "type": "front_chat",
    "decision_tree_responses": [
      {
        "timestamp": 1689272457222,
        "nodeId": "83b60472-e384-423f-acba-1865db396d07",
        "nodeData": {
          "type": "message",
          "message": "Hi! We're here to help!"
        },
        "responseData": {
          "nodeType": "message"
        }
      },
      {
        "timestamp": 1689272459545,
        "nodeId": "4e7531f5-b079-483c-8ab8-f43b983240e8",
        "nodeData": {
          "type": "multi_choice",
          "message": "hello",
          "options": [
            {
              "sourceHandle": "c10063a5-7767-4503-b7ef-cbd00ca67e93",
              "value": "1"
            },
            {
              "sourceHandle": "b7e9b29b-c13d-4ca2-8f72-7d18d9d7d3b8",
              "value": "2"
            }
          ]
        },
        "responseData": {
          "nodeType": "multi_choice",
          "response": "1",
          "responseLabel": "1"
        }
      },
      {
        "timestamp": 1689272465080,
        "nodeId": "b0f75d70-8206-441e-80f7-6f245ace468e",
        "nodeData": {
          "type": "prompt",
          "message": "woof woof"
        },
        "responseData": {
          "nodeType": "prompt",
          "response": "hallo thar sir!"
        }
      },
      {
        "timestamp": 1689272471716,
        "nodeId": "ea938ea9-c9d7-467a-83da-c33f05533a05",
        "nodeData": {
          "type": "custom_fields",
          "customFields": [
            {
              "customFieldId": -1,
              "fieldName": "Name",
              "fieldType": "string",
              "isRequired": false,
              "resourceType": "card"
            },
            {
              "customFieldId": -2,
              "fieldName": "Email",
              "fieldType": "email",
              "isRequired": false,
              "resourceType": "card"
            }
          ]
        },
        "responseData": {
          "nodeType": "custom_fields",
          "customFieldResponses": [
            {
              "customFieldId": -1,
              "fieldName": "Name",
              "fieldType": "string",
              "isRequired": false,
              "resourceType": "card",
              "response": "bruce"
            },
            {
              "customFieldId": -2,
              "fieldName": "Email",
              "fieldType": "email",
              "isRequired": false,
              "resourceType": "card",
              "response": "bruce@email.com"
            }
          ]
        }
      },
      {
        "timestamp": 1689272471717,
        "nodeId": "2",
        "nodeData": {
          "type": "end"
        },
        "responseData": {
          "nodeType": "end"
        }
      }
    ],
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"
  },
  "default_font_style": "",
  "main_style": "",
  "variable_values": [],
  "calendar_events": [],
  "history_paths": [],
  "raw_incoming_path": "024079322600db4c8f9998fe7738b1a8/frontChat/137",
  "email_rfc822_path": null,
  "signature_id": null,
  "handle_times": {}
}