Front Channels Platform API
Build custom messaging channels that bridge Front to proprietary messaging platforms (e.g. internal portals, niche chat networks).
OpenAPI Specification
{
"openapi": "3.0.0",
"x-api-id": "front",
"x-explorer-enabled": false,
"x-proxy-enabled": true,
"x-samples-enabled": true,
"info": {
"version": "1.0.0",
"title": "Channel API",
"contact": {
"name": "Front Platform",
"url": "https://community.front.com"
}
},
"security": [
{
"http": []
}
],
"servers": [
{
"url": "https://api2.frontapp.com"
}
],
"components": {
"securitySchemes": {
"http": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"responses": {
"acceptedMessage": {
"description": "An accepted message",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"default": "accepted"
},
"message_uid": {
"type": "string",
"description": "Message unique identifier"
}
}
}
}
}
},
"applicationMessageTemplate": {
"description": "An application message template",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationMessageTemplateResponse"
}
}
}
}
},
"schemas": {
"AddCallRecordingFormFields": {
"type": "object",
"required": [
"recording_type"
],
"properties": {
"recording_type": {
"type": "string",
"enum": [
"call",
"voicemail"
]
}
}
},
"AddCallSummary": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"minLength": 1,
"description": "Summary text for the call."
}
}
},
"AddCallTranscript": {
"type": "object",
"required": [
"lines"
],
"properties": {
"lines": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TranscriptLine"
}
}
}
},
"ApplicationMessageTemplate": {
"required": [
"external_id",
"name",
"blurb",
"is_disabled",
"status_name",
"variable_mappings",
"template_preview"
],
"allOf": [
{
"$ref": "#/components/schemas/ApplicationMessageTemplateEditBlob"
},
{
"type": "object",
"properties": {
"external_id": {
"type": "string"
}
}
}
]
},
"ApplicationMessageTemplateEditBlob": {
"properties": {
"name": {
"type": "string",
"description": "Name of the message template."
},
"blurb": {
"type": "string",
"description": "A limited preview of the message template content."
},
"is_disabled": {
"type": "boolean",
"description": "Whether the message template is enabled for use in the external service."
},
"status_name": {
"type": "string",
"description": "Either \"PENDING\", \"APPROVED\", or \"REJECTED\". This value helps admins understand why a template may be enabled or disabled in the external service."
},
"variable_mappings": {
"type": "array",
"description": "List of variable mappings",
"items": {
"type": "object",
"required": [
"uid",
"type",
"name"
],
"properties": {
"uid": {
"type": "string",
"description": "Value of the variable"
},
"name": {
"type": "string",
"description": "Name of the variable"
},
"type": {
"type": "string",
"description": "Type of the variable"
}
}
}
},
"template_preview": {
"type": "string",
"description": "Preview of the template"
}
}
},
"ApplicationMessageTemplateResponse": {
"description": "Response for an application message template.",
"type": "object",
"properties": {
"template_id": {
"type": "number",
"description": "ID of the application message template",
"example": "msg_777"
}
}
},
"CallParty": {
"type": "object",
"required": [
"handle"
],
"properties": {
"handle": {
"type": "string",
"description": "Party identifier compatible with the application channel contact type."
},
"name": {
"type": "string",
"description": "Optional display name for the party."
}
}
},
"CreateCall": {
"discriminator": {
"propertyName": "direction",
"mapping": {
"inbound": "#/components/schemas/CreateCallInbound",
"outbound": "#/components/schemas/CreateCallOutbound"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/CreateCallInbound"
},
{
"$ref": "#/components/schemas/CreateCallOutbound"
}
],
"properties": {
"direction": {
"type": "string",
"enum": [
"inbound",
"outbound"
],
"description": "Use `inbound` with required `from` (external party); use `outbound` with required `to` (callee)."
}
}
},
"CreateCallInbound": {
"type": "object",
"required": [
"external_call_id",
"initial_status",
"direction",
"from",
"parent_external_call_id"
],
"properties": {
"external_call_id": {
"type": "string",
"description": "Stable identifier for this call in the provider system."
},
"initial_status": {
"type": "string",
"enum": [
"queued",
"ringing"
]
},
"direction": {
"type": "string",
"enum": [
"inbound"
],
"description": "Inbound calls must include `from` (external party who initiated). The channel is treated as the receiving side (e.g. agent or queue)."
},
"from": {
"$ref": "#/components/schemas/CallParty",
"description": "External party who initiated the inbound call."
},
"started_at": {
"type": "number",
"description": "Optional Unix timestamp (ms) when the call started."
},
"parent_external_call_id": {
"type": "string",
"description": "External ID of the parent call (e.g. where the call was transferred from). This will be used to thread the call into an existing conversation with a matching parent call ID."
},
"agent_email_address": {
"type": "string",
"description": "Optional email of the teammate associated with the call."
}
}
},
"CreateCallOutbound": {
"type": "object",
"required": [
"external_call_id",
"initial_status",
"direction",
"to",
"parent_external_call_id"
],
"properties": {
"external_call_id": {
"type": "string",
"description": "Stable identifier for this call in the provider system."
},
"initial_status": {
"type": "string",
"enum": [
"queued",
"ringing"
]
},
"direction": {
"type": "string",
"enum": [
"outbound"
],
"description": "Outbound calls must include `to` (callee). The channel is treated as the originating side (e.g. agent)."
},
"to": {
"$ref": "#/components/schemas/CallParty",
"description": "Party being called (callee)."
},
"started_at": {
"type": "number",
"description": "Optional Unix timestamp (ms) when the call started."
},
"parent_external_call_id": {
"type": "string",
"description": "External ID of the parent call (e.g. where the call was transferred from). This will be used to thread the call into an existing conversation with a matching parent call ID."
},
"agent_email_address": {
"type": "string",
"description": "Optional email of the teammate associated with the call."
}
}
},
"InboundMessage": {
"required": [
"sender",
"body",
"metadata"
],
"properties": {
"sender": {
"type": "object",
"description": "Data of the sender",
"required": [
"handle"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the sender"
},
"handle": {
"type": "string",
"description": "Handle of the sender. It can be any string used to uniquely identify the sender. **Important:** When sending a phone number, include a country code preceded by a plus (+) sign. For example, +33 for France. If you do not send a country code or include a plus sign, Front will normalize your phone number to the USA (+1)."
},
"email": {
"type": "string",
"description": "Email of the sender. When provided, links this contact to existing contacts with the same email to prevent duplicates across channels."
}
}
},
"subject": {
"type": "string",
"description": "Subject of the message"
},
"body": {
"type": "string",
"description": "The body of the message in HTML or plain text format."
},
"metadata": {
"type": "object",
"required": [
"external_id",
"external_conversation_id"
],
"properties": {
"external_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the message"
},
"external_conversation_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the conversation. Will be used to thread messages."
},
"referenced_message_external_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the message that this message is replying to. Use this for explicit replies."
}
}
},
"delivered_at": {
"type": "integer",
"description": "Time in seconds at which message was created in external system"
},
"attachments": {
"description": "Binary data of attached files. Must use `Content-Type: multipart/form-data` if specified. See [example](https://gist.github.com/hdornier/e04d04921032e98271f46ff8a539a4cb) or read more about [Attachments](https://dev.frontapp.com/docs/attachments-1). Max 25 MB.",
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
},
"OutboundMessage": {
"required": [
"to",
"body",
"metadata"
],
"description": "Payload to receive an outbound message from an external system into Front.",
"properties": {
"sender_name": {
"type": "string",
"description": "Name of the sender"
},
"to": {
"type": "array",
"description": "Data of the message recipient",
"items": {
"type": "object",
"required": [
"handle"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the recipient"
},
"handle": {
"type": "string",
"description": "Handle of the recipient. It can be any string used to uniquely identify the sender. **Important:** When sending a phone number, include a country code preceded by a plus (+) sign. For example, +33 for France. If you do not send a country code or include a plus sign, Front will normalize your phone number to the USA (+1)."
},
"email": {
"type": "string",
"description": "Email of the recipient. When provided, links this contact to existing contacts with the same email to prevent duplicates across channels."
}
}
}
},
"subject": {
"type": "string",
"description": "Subject of the message"
},
"author_id": {
"type": "string",
"description": "ID of the teammate on behalf of whom the message is sent"
},
"body": {
"type": "string",
"description": "The body of the message in HTML or plain text format."
},
"metadata": {
"type": "object",
"required": [
"external_id",
"external_conversation_id"
],
"properties": {
"external_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the message"
},
"external_conversation_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the conversation. Will be used to thread messages."
},
"referenced_message_external_id": {
"type": "string",
"maxLength": 200,
"description": "External identifier of the message that this message is replying to. Use this for explicit replies."
}
}
},
"delivered_at": {
"type": "integer",
"description": "Time in seconds at which message was created in external system"
},
"attachments": {
"description": "Binary data of attached files. Must use `Content-Type: multipart/form-data` if specified. See [example](https://gist.github.com/hdornier/e04d04921032e98271f46ff8a539a4cb) or read more about [Attachments](https://dev.frontapp.com/docs/attachments-1). Max 25 MB.",
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
},
"TranscriptLine": {
"type": "object",
"required": [
"speaker_name",
"content",
"start_time_seconds",
"speaker_type"
],
"properties": {
"speaker_name": {
"type": "string"
},
"content": {
"type": "string"
},
"start_time_seconds": {
"type": "number"
},
"speaker_type": {
"type": "string",
"enum": [
"internal",
"external"
],
"description": "internal for agent or system-side speech; external for the other party."
}
}
},
"UpdateCall": {
"type": "object",
"required": [
"call_status"
],
"properties": {
"occurred_at": {
"type": "number",
"description": "Optional Unix timestamp (ms) when this status change occurred."
},
"call_status": {
"type": "string",
"enum": [
"queued",
"ringing",
"connected",
"hold",
"hangup",
"abandoned",
"missed",
"transferred"
]
},
"agent_email_address": {
"type": "string",
"description": "Optional; include when the status update relates to a specific teammate."
}
}
},
"UpdateChannel": {
"properties": {
"status": {
"type": "string",
"description": "Status of the channel",
"enum": [
"offline",
"ok"
]
}
}
}
}
},
"paths": {
"/channels/{channel_id}": {
"patch": {
"summary": "Update Channel",
"operationId": "update-channel",
"description": "Update a channel.",
"tags": [
"Channels"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID. Alternatively, you can supply the channel address as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).",
"schema": {
"type": "string",
"default": "cha_123"
}
}
],
"requestBody": {
"description": "Channel details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateChannel"
}
}
}
},
"responses": {
"204": {
"description": "No content"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/application_message_templates": {
"put": {
"summary": "Sync application message template",
"operationId": "sync-application-message-template",
"description": "Import an application message template from an external service (such as WhatsApp or Facebook). The message template becomes available for use by the channel specified if configured as described in [this topic](https://dev.frontapp.com/update/docs/application-channel-message-templates).",
"tags": [
"Application Message Templates"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The channel ID. Alternatively, you can supply the channel address as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).",
"schema": {
"type": "string",
"default": "cha_123"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationMessageTemplate"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/applicationMessageTemplate"
},
"400": {
"description": "Channel is not an application channel or does not support application message templates."
}
},
"x-required-scopes": [
"message_templates:write"
]
}
},
"/channels/{channel_id}/application_message_templates/{external_id}": {
"patch": {
"summary": "Update application message template",
"operationId": "update-application-message-template",
"description": "Update an application message template that already exists in Front.",
"tags": [
"Application Message Templates"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The channel ID. Alternatively, you can supply the channel address as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "external_id",
"required": true,
"description": "The external ID of the application message template.",
"schema": {
"type": "string",
"default": "ext_123"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationMessageTemplateEditBlob"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/applicationMessageTemplate"
},
"400": {
"description": "Channel is not an application channel or does not support application message templates."
}
},
"x-required-scopes": [
"message_templates:write"
]
}
},
"/channels/{channel_id}/calls": {
"post": {
"summary": "Create a call",
"operationId": "create-call",
"description": "Creates a call in Front.",
"tags": [
"Calls"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID.",
"schema": {
"type": "string",
"default": "cha_123"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCall"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/calls/{external_call_id}": {
"patch": {
"summary": "Update call status",
"operationId": "update-call",
"description": "Updates the call status of a call in Front.",
"tags": [
"Calls"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID.",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "external_call_id",
"required": true,
"description": "The external call ID from the provider system (same as `external_call_id` on create).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCall"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/calls/{external_call_id}/recording": {
"post": {
"summary": "Add call recording",
"operationId": "add-call-recording",
"description": "Adds a recording to a call in Front. Send `multipart/form-data` with exactly one file in the `attachments` field, `Content-Type: audio/*`, and required `recording_type` (`call` or `voicemail`).\n",
"tags": [
"Calls"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID.",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "external_call_id",
"required": true,
"description": "The external call ID from the provider system.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"attachments",
"recording_type"
],
"properties": {
"attachments": {
"type": "string",
"format": "binary",
"description": "Exactly one audio file (`audio/*`)."
},
"recording_type": {
"type": "string",
"enum": [
"call",
"voicemail"
]
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/calls/{external_call_id}/summary": {
"post": {
"summary": "Add call summary",
"operationId": "add-call-summary",
"description": "Adds a summary to a call in Front.",
"tags": [
"Calls"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID.",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "external_call_id",
"required": true,
"description": "The external call ID from the provider system.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddCallSummary"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/calls/{external_call_id}/transcript": {
"post": {
"summary": "Add call transcript",
"operationId": "add-call-transcript",
"description": "Adds a transcript to a call in Front.",
"tags": [
"Calls"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The Channel ID.",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "external_call_id",
"required": true,
"description": "The external call ID from the provider system.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddCallTranscript"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request"
}
},
"x-required-scopes": [
"channels:write"
]
}
},
"/channels/{channel_id}/conversations/{conv_ext_id}/messages/{message_ext_id}/status": {
"put": {
"summary": "Update external message status",
"operationId": "update-external-message-status",
"description": "Update the status of an outbound message by external ID. This endpoint is used by external systems (like SMS providers or custom channels)\nto notify Front when a message's delivery status has changed.\n\n**Available status changes:**\n- `failed`: Mark a message as failed. When marked as failed, the conversation is reopened so the team can take action.\n\n**Note:** This endpoint is only available for outbound messages.\n",
"tags": [
"Messages"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The channel ID. Alternatively, you can supply the channel address as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).",
"schema": {
"type": "string",
"default": "cha_123"
}
},
{
"in": "path",
"name": "conv_ext_id",
"required": true,
"description": "The conversation's external ID.",
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "message_ext_id",
"required": true,
"description": "The message's external ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"failed"
],
"description": "The status to set for the message. Currently only 'failed' is supported."
},
"reason": {
"type": "string",
"description": "Optional reason for the status change. This will be displayed to users and logged for debugging purposes."
}
}
}
}
}
},
"responses": {
"204": {
"description": "No content"
}
},
"x-required-scopes": [
"messages:write"
]
}
},
"/channels/{channel_id}/inbound_messages": {
"post": {
"summary": "Sync inbound message",
"operationId": "sync-inbound-message",
"description": "Import a message that was received by the channel.",
"tags": [
"Messages"
],
"parameters": [
{
"in": "path",
"name": "channel_id",
"required": true,
"description": "The channel ID. Alternatively, you can supply the channel address as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).",
"schema": {
"type": "string",
"default": "cha_123"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InboundMessage"
}
}
}
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/front/refs/heads/main/openapi/front-channel-api-openapi.json