{
  "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"
              }
            }
          }
        },
        "responses": {
          "202": {
            "$ref": "#/components/responses/acceptedMessage"
          }
        },
        "x-required-scopes": [
          "messages:write"
        ]
      }
    },
    "/channels/{channel_id}/outbound_messages": {
      "post": {
        "summary": "Sync outbound message",
        "operationId": "sync-outbound-message",
        "description": "Import a message that was sent from 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/OutboundMessage"
              }
            }
          }
        },
        "responses": {
          "202": {
            "$ref": "#/components/responses/acceptedMessage"
          }
        },
        "x-required-scopes": [
          "messages:write"
        ]
      }
    }
  }
}