Frontline Agent Channels API

openapi: 3.2.0
info:
  title: Public Agent Channels API
  version: 1.0.0
  description: 'Public API for accessing agents, flows, and analytics.


    ## Authentication


    The Public API supports two API key types. Pass the key as a Bearer token:


    ```

    Authorization: Bearer <YOUR_API_KEY>

    ```


    ### Account API key (GENERAL)


    Account-level key that acts on behalf of the entire account. Required for account-level endpoints unless noted otherwise.


    ### User API key (USER)


    User-level key tied to a specific user. Required for write operations and user-owned resources. **Also accepted on all account-level endpoints.**


    Each operation documents which key type(s) it accepts in its **Security** section.'
  license:
    name: Proprietary
    url: https://www.getfrontline.ai/terms-and-conditions
servers:
- url: https://prod-api.getfrontline.ai
tags:
- name: Agent Channels
  description: View connected channel integrations (WhatsApp, Instagram, Messenger) and bind numbers/accounts/pages to agents
paths:
  /public/v1/channels:
    get:
      summary: List channel integrations
      operationId: listChannelIntegrations
      description: Returns the account's connected channel integrations (WhatsApp, Instagram, Messenger) and which agent each number/account/page is bound to. Connecting a channel requires the OAuth flow in the app and is not available via the API. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      responses:
        '200':
          description: The account's channel integrations (null if none connected)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicChannelIntegrations'
  /public/v1/channels/whatsapp/numbers/{phoneNumberId}/business-info:
    get:
      summary: Get WhatsApp number business info
      operationId: getWhatsAppNumberBusinessInfo
      description: Returns the live WhatsApp Business profile (about, address, websites, category) for a connected number. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: string
          example: '109876543210123'
        required: true
        name: phoneNumberId
        in: path
      responses:
        '200':
          description: The WhatsApp business profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWhatsAppBusinessInfo'
  /public/v1/channels/whatsapp/{integrationId}/numbers/{phoneNumberId}:
    put:
      summary: Update WhatsApp number (profile + agent)
      operationId: updateWhatsAppNumber
      description: Updates a WhatsApp number's business profile and/or binds it to an agent. Pass `agentId` to bind, null to unbind, or omit to leave the binding unchanged. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: integer
          example: 12
          exclusiveMinimum: 0
        required: true
        name: integrationId
        in: path
      - schema:
          type: string
          example: '109876543210123'
        required: true
        name: phoneNumberId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicWhatsAppNumberUpdateInput'
      responses:
        '200':
          description: The updated WhatsApp number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWhatsAppNumber'
  /public/v1/channels/whatsapp/{integrationId}/numbers/{phoneNumberId}/register:
    post:
      summary: Register WhatsApp number
      operationId: registerWhatsAppNumber
      description: Registers a connected WhatsApp number with Meta (generates a PIN and completes registration). Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: integer
          example: 12
          exclusiveMinimum: 0
        required: true
        name: integrationId
        in: path
      - schema:
          type: string
          example: '109876543210123'
        required: true
        name: phoneNumberId
        in: path
      responses:
        '204':
          description: Registered
  /public/v1/channels/whatsapp/{integrationId}/numbers/{phoneNumberId}/disconnect:
    post:
      summary: Disconnect WhatsApp number
      operationId: disconnectWhatsAppNumber
      description: Disconnects a single WhatsApp number from the integration. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: integer
          example: 12
          exclusiveMinimum: 0
        required: true
        name: integrationId
        in: path
      - schema:
          type: string
          example: '109876543210123'
        required: true
        name: phoneNumberId
        in: path
      responses:
        '204':
          description: Disconnected
  /public/v1/channels/instagram/accounts/{instagramAccountId}:
    put:
      summary: Assign Instagram account to agent
      operationId: assignInstagramAccount
      description: Binds (or, with null, unbinds) a connected Instagram account to an agent. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: integer
          example: 5
          exclusiveMinimum: 0
        required: true
        name: instagramAccountId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicChannelAssignInput'
      responses:
        '200':
          description: The updated Instagram account
  /public/v1/channels/messenger/pages/{messengerPageId}:
    put:
      summary: Assign Messenger page to agent
      operationId: assignMessengerPage
      description: Binds (or, with null, unbinds) a connected Messenger page to an agent. Requires a USER API key.
      security:
      - userApiKey: []
      tags:
      - Agent Channels
      parameters:
      - schema:
          type: integer
          example: 7
          exclusiveMinimum: 0
        required: true
        name: messengerPageId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicChannelAssignInput'
      responses:
        '200':
          description: The updated Messenger page
components:
  schemas:
    PublicWhatsAppBusinessInfo:
      type: object
      properties:
        about:
          type:
          - string
          - 'null'
        address:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        profile_picture_url:
          type:
          - string
          - 'null'
        websites:
          type:
          - array
          - 'null'
          items:
            type: string
        vertical:
          type:
          - string
          - 'null'
          enum:
          - AUTO
          - BEAUTY
          - APPAREL
          - EDU
          - ENTERTAIN
          - EVENT_PLAN
          - FINANCE
          - GROCERY
          - GOVT
          - HOTEL
          - HEALTH
          - NONPROFIT
          - PROF_SERVICES
          - RETAIL
          - TRAVEL
          - RESTAURANT
          - OTHER
          - UNDEFINED
    PublicChannelAssignInput:
      type: object
      properties:
        agentId:
          type:
          - string
          - 'null'
          example: asst_123
      required:
      - agentId
    PublicWhatsAppNumber:
      type: object
      properties:
        id:
          type: number
        phoneNumberId:
          type: string
        assistantId:
          type:
          - string
          - 'null'
        assistant:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            name:
              type: string
          required:
          - id
          - name
        status:
          type: string
          enum:
          - CONNECTED
          - PENDING
          - UNREGISTERED
          - ERROR
          - VERIFICATION_PENDING
          - DELETED
        wabaId:
          type: string
        name:
          type: string
        about:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        address:
          type:
          - string
          - 'null'
        category:
          type: string
          enum:
          - AUTO
          - BEAUTY
          - APPAREL
          - EDU
          - ENTERTAIN
          - EVENT_PLAN
          - FINANCE
          - GROCERY
          - GOVT
          - HOTEL
          - HEALTH
          - NONPROFIT
          - PROF_SERVICES
          - RETAIL
          - TRAVEL
          - RESTAURANT
          - OTHER
          - UNDEFINED
        displayPhoneNumber:
          type: string
        website:
          type:
          - string
          - 'null'
        secondaryWebsite:
          type:
          - string
          - 'null'
        verificationStatus:
          type: string
          enum:
          - VERIFIED
          - NOT_VERIFIED
        image:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - phoneNumberId
      - assistantId
      - status
      - wabaId
      - name
      - about
      - description
      - address
      - category
      - displayPhoneNumber
      - website
      - secondaryWebsite
      - verificationStatus
      - image
      - email
      - createdAt
      - updatedAt
    PublicWhatsAppNumberUpdateInput:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          maxLength: 512
        website:
          type:
          - string
          - 'null'
          maxLength: 256
        secondaryWebsite:
          type:
          - string
          - 'null'
          maxLength: 256
        address:
          type:
          - string
          - 'null'
          maxLength: 256
        email:
          type:
          - string
          - 'null'
          maxLength: 128
          format: email
        about:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 139
        category:
          type:
          - string
          - 'null'
          enum:
          - AUTO
          - BEAUTY
          - APPAREL
          - EDU
          - ENTERTAIN
          - EVENT_PLAN
          - FINANCE
          - GROCERY
          - GOVT
          - HOTEL
          - HEALTH
          - NONPROFIT
          - PROF_SERVICES
          - RETAIL
          - TRAVEL
          - RESTAURANT
          - OTHER
          - UNDEFINED
        agentId:
          type:
          - string
          - 'null'
          example: asst_123
    PublicChannelIntegrations:
      type:
      - object
      - 'null'
      properties:
        id:
          type: number
        accountId:
          type: number
        whatsapp:
          type:
          - object
          - 'null'
          properties:
            id:
              type: number
            integrationId:
              type: number
            status:
              type: string
              enum:
              - PENDING
              - ACTIVE
              - DELETED
            integratedById:
              type: number
            integratedBy:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                avatar:
                  type:
                  - string
                  - 'null'
              required:
              - firstName
              - lastName
            phoneNumbers:
              type: array
              items:
                $ref: '#/components/schemas/PublicWhatsAppNumber'
            allocationId:
              type:
              - string
              - 'null'
            expirationTime:
              type:
              - string
              - 'null'
            createdAt:
              type: string
            updatedAt:
              type: string
          required:
          - id
          - integrationId
          - status
          - integratedById
          - integratedBy
          - phoneNumbers
          - allocationId
          - createdAt
          - updatedAt
        instagram:
          type:
          - object
          - 'null'
          properties:
            id:
              type: number
            integrationId:
              type: number
            status:
              type: string
              enum:
              - PENDING
              - ACTIVE
              - EXPIRED
              - DELETED
            integratedById:
              type: number
            integratedBy:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                avatar:
                  type:
                  - string
                  - 'null'
              required:
              - firstName
              - lastName
            instagramAccounts:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: number
                  instagramUserId:
                    type: string
                  username:
                    type: string
                  accountType:
                    type: string
                    enum:
                    - BUSINESS
                    - CREATOR
                  profilePictureUrl:
                    type:
                    - string
                    - 'null'
                  followersCount:
                    type:
                    - number
                    - 'null'
                  mediaCount:
                    type:
                    - number
                    - 'null'
                  assistantId:
                    type:
                    - string
                    - 'null'
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                - id
                - instagramUserId
                - username
                - accountType
                - profilePictureUrl
                - followersCount
                - mediaCount
                - assistantId
                - createdAt
                - updatedAt
            tokenExpiresAt:
              type:
              - string
              - 'null'
            createdAt:
              type: string
            updatedAt:
              type: string
          required:
          - id
          - integrationId
          - status
          - integratedById
          - integratedBy
          - instagramAccounts
          - tokenExpiresAt
          - createdAt
          - updatedAt
        messenger:
          type:
          - object
          - 'null'
          properties:
            id:
              type: number
            integrationId:
              type: number
            status:
              type: string
              enum:
              - PENDING
              - ACTIVE
              - EXPIRED
              - DELETED
            integratedById:
              type: number
            integratedBy:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                avatar:
                  type:
                  - string
                  - 'null'
              required:
              - firstName
              - lastName
            messengerPages:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: number
                  messengerPageId:
                    type: string
                  businessAccountId:
                    type:
                    - string
                    - 'null'
                  pageName:
                    type: string
                  pageType:
                    type: string
                    enum:
                    - business
                  pagePictureUrl:
                    type:
                    - string
                    - 'null'
                  followersCount:
                    type:
                    - number
                    - 'null'
                  likesCount:
                    type:
                    - number
                    - 'null'
                  assistantId:
                    type:
                    - string
                    - 'null'
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                - id
                - messengerPageId
                - businessAccountId
                - pageName
                - pageType
                - pagePictureUrl
                - followersCount
                - likesCount
                - assistantId
                - createdAt
                - updatedAt
            createdAt:
              type: string
            updatedAt:
              type: string
          required:
          - id
          - integrationId
          - status
          - integratedById
          - integratedBy
          - messengerPages
          - createdAt
          - updatedAt
      required:
      - id
      - accountId
      - whatsapp
      - instagram
      - messenger
  securitySchemes:
    accountApiKey:
      type: http
      scheme: bearer
      bearerFormat: Account API Key
      description: Account-level API key (GENERAL). Authenticates on behalf of the entire account. Use for read-only and analytics endpoints marked as account-level in this documentation.
    userApiKey:
      type: http
      scheme: bearer
      bearerFormat: User API Key
      description: User-level API key (USER). Authenticates on behalf of a specific user. Required for write operations and user-owned resources. Also accepted on all account-level endpoints.
x-tagGroups:
- name: Agent Builder
  tags:
  - Agent Builder
  - Flows
  - Flow Variables
  - Intents
  - Agents
  - Agent Playbooks
- name: Workflows
  tags:
  - Workflows
  - Workflow Variables
- name: Objects
  tags:
  - Objects
  - Object fields
  - Object options
  - Object record types
  - Object views
  - Object relations
  - Object rows
  - Object aggregations
  - Object activities
  - Object tasks
  - Object files
  - Object export
- name: Tables
  tags:
  - Tables
  - Table fields
  - Table options
  - Table rows
  - Table aggregations
  - Table activities
  - Table tasks
  - Table files
  - Table export
- name: Channels
  tags:
  - Channels
- name: Integrations
  tags:
  - Custom Tools
  - Incoming Webhooks
  - Account Integrations
  - Agent Channels
  - Integration Resources
- name: Knowledge
  tags:
  - Knowledge Bases
- name: Core
  tags:
  - Account
  - AI Models
  - Billing
  - Users
  - User Tasks
  - Guidance