GuidesAPI ReferenceChangelogCommunity
API Reference
Front
Start typing to search…

Messages

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:

TypeDescription
emailEmail message
tweetMessage from Twitter
tweet_dmDirect Message from Twitter
googleplayGooglePlay message
smsSMS message
whatsappWhatsApp message
smoochMessage from Smooch
facebookMessage from Facebook
intercomMessage from Intercom
callPhone call
customCustom Message
front_chatFront 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 messageu_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.

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": "[email protected]",
    "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": "[email protected]",
      "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": "<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": "[email protected]"
            }
          ]
        }
      },
      {
        "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: [email protected]",
  "json": {
    "attachments": [],
    "sender": {
      "handle": "39fe4d09-a31f-4faa-b91e-ab13b62ad374",
      "customFields": {},
      "contact": {
        "name": "bruce",
        "email": "[email protected]"
      }
    },
    "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": "<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": "[email protected]"
            }
          ]
        }
      },
      {
        "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": {}
}