Messenger Platform API

openapi: 3.0.3
info:
  title: Facebook Messenger Platform API
  description: >-
    Build messaging experiences on Facebook Messenger and Instagram Direct.
    Send and receive messages, create bot interactions, use templates, and
    manage conversation routing.
  version: '21.0'
  contact:
    name: Meta Platforms
    url: https://developers.facebook.com
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://graph.facebook.com/v21.0
    description: Messenger Platform API v21.0
security:
  - BearerAuth: []
paths:
  /{page-id}/messages:
    post:
      operationId: sendMessage
      summary: Facebook Send Message
      description: Send a message to a user via Messenger.
      tags:
        - Messages
      parameters:
        - name: page-id
          in: path
          required: true
          description: The page ID.
          schema:
            type: string
          example: '200001234567890'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              SendMessageRequestExample:
                summary: Default sendMessage request
                x-microcks-default: true
                value:
                  recipient:
                    id: '100001234567890'
                  messaging_type: RESPONSE
                  message:
                    text: Hello! How can I help you today?
      responses:
        '200':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              examples:
                SendMessage200Example:
                  summary: Default sendMessage 200 response
                  x-microcks-default: true
                  value:
                    recipient_id: '100001234567890'
                    message_id: mid.1234567890
        '400':
          description: Invalid message request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{page-id}/messenger_profile:
    get:
      operationId: getMessengerProfile
      summary: Facebook Get Messenger Profile
      description: Retrieve the Messenger profile settings for a page.
      tags:
        - Profile
      parameters:
        - name: page-id
          in: path
          required: true
          description: The page ID.
          schema:
            type: string
          example: '200001234567890'
        - name: fields
          in: query
          description: Comma-separated list of profile fields.
          schema:
            type: string
          example: greeting,get_started,persistent_menu
      responses:
        '200':
          description: Messenger profile retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessengerProfile'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updateMessengerProfile
      summary: Facebook Update Messenger Profile
      description: Update the Messenger profile settings for a page.
      tags:
        - Profile
      parameters:
        - name: page-id
          in: path
          required: true
          description: The page ID.
          schema:
            type: string
          example: '200001234567890'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessengerProfileUpdate'
      responses:
        '200':
          description: Profile updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{conversation-id}:
    get:
      operationId: getConversation
      summary: Facebook Get Conversation
      description: Retrieve a conversation by ID.
      tags:
        - Conversations
      parameters:
        - name: conversation-id
          in: path
          required: true
          description: The conversation ID.
          schema:
            type: string
          example: 't_100001234567890'
      responses:
        '200':
          description: Conversation retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{page-id}/conversations:
    get:
      operationId: listConversations
      summary: Facebook List Conversations
      description: Retrieve all conversations for a page.
      tags:
        - Conversations
      parameters:
        - name: page-id
          in: path
          required: true
          description: The page ID.
          schema:
            type: string
          example: '200001234567890'
      responses:
        '200':
          description: Conversations retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Page access token with pages_messaging permission.
  schemas:
    SendMessageRequest:
      type: object
      description: Request to send a message.
      properties:
        recipient:
          type: object
          description: Message recipient.
          properties:
            id:
              type: string
              description: Recipient user ID.
              example: '100001234567890'
          required:
            - id
        messaging_type:
          type: string
          description: Messaging type.
          enum:
            - RESPONSE
            - UPDATE
            - MESSAGE_TAG
          example: RESPONSE
        message:
          type: object
          description: Message content.
          properties:
            text:
              type: string
              description: Message text.
              example: Hello! How can I help you today?
            attachment:
              type: object
              description: Message attachment.
              properties:
                type:
                  type: string
                  enum:
                    - image
                    - audio
                    - video
                    - file
                    - template
                payload:
                  type: object
      required:
        - recipient
        - messaging_type
        - message
    SendMessageResponse:
      type: object
      description: Response from sending a message.
      properties:
        recipient_id:
          type: string
          description: Recipient user ID.
          example: '100001234567890'
        message_id:
          type: string
          description: Sent message ID.
          example: mid.1234567890
    MessengerProfile:
      type: object
      description: Messenger profile settings.
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              greeting:
                type: array
                items:
                  type: object
                  properties:
                    locale:
                      type: string
                    text:
                      type: string
              get_started:
                type: object
                properties:
                  payload:
                    type: string
              persistent_menu:
                type: array
                items:
                  type: object
    MessengerProfileUpdate:
      type: object
      description: Update for Messenger profile settings.
      properties:
        greeting:
          type: array
          items:
            type: object
            properties:
              locale:
                type: string
                example: default
              text:
                type: string
                example: Welcome to our page!
        get_started:
          type: object
          properties:
            payload:
              type: string
              example: GET_STARTED
    Conversation:
      type: object
      description: A Messenger conversation.
      properties:
        id:
          type: string
          description: Conversation ID.
          example: 't_100001234567890'
        updated_time:
          type: string
          format: date-time
          description: Last update time.
        participants:
          type: object
          description: Conversation participants.
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
        messages:
          type: object
          description: Messages in the conversation.
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Message'
    ConversationList:
      type: object
      description: Paginated list of conversations.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
        paging:
          type: object
          properties:
            cursors:
              type: object
              properties:
                before:
                  type: string
                after:
                  type: string
            next:
              type: string
              format: uri
    Message:
      type: object
      description: A message in a conversation.
      properties:
        id:
          type: string
          description: Message ID.
          example: mid.1234567890
        message:
          type: string
          description: Message text.
          example: Hello!
        created_time:
          type: string
          format: date-time
          description: Message creation time.
        from:
          type: object
          properties:
            id:
              type: string
            name:
              type: string