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 message | |
| tweet | Message from Twitter |
| tweet_dm | Direct Message from Twitter |
| googleplay | GooglePlay message |
| sms | SMS message |
| WhatsApp message | |
| smooch | Message from Smooch |
| 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,textas well as recipients'handleare replaced by the string[REDACTED]for messages of typetweetortweet_dmonly.For those messages, the payload includes the field
metadata.external_idcontaining 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": "[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": {}
}