Brevo Conversations API

openapi: 3.1.0
info:
  title: Brevo Conversations API
  description: >-
    The Brevo Conversations API provides programmatic access to live chat and
    messaging features for customer support and engagement. It enables
    developers to manage chat conversations, send and receive messages, and
    integrate Brevo's chat widget into websites and applications. The API
    supports real-time communication with site visitors and can be used to
    build custom chat interfaces, automate responses, and route conversations
    to appropriate team members.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
  description: Brevo Conversations Documentation
  url: https://developers.brevo.com/docs/getting-started-with-conversations-api
servers:
  - url: https://api.brevo.com/v3
    description: Brevo Production API Server
tags:
  - name: Agent Status
    description: >-
      Manage agent online status for conversation availability.
  - name: Automated Messages
    description: >-
      Create, manage, and retrieve automated messages pushed to visitors.
  - name: Messages
    description: >-
      Send and manage chat messages as an agent or automated bot within
      conversations.
security:
  - apiKeyAuth: []
paths:
  /conversations/messages:
    post:
      operationId: sendMessageAsAgent
      summary: Send a message as an agent
      description: >-
        Sends a chat message within a conversation as an agent. The
        message is delivered to the visitor in real time through the
        Brevo chat widget.
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessage'
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/messages/{messageId}:
    get:
      operationId: getMessage
      summary: Get a message
      description: >-
        Retrieves the details of a specific chat message by its unique
        identifier including the message text, sender, and timestamp.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/messageIdParam'
      responses:
        '200':
          description: Message retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateMessage
      summary: Update a message
      description: >-
        Updates the text content of an existing chat message. Only
        agent messages can be updated.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/messageIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  description: >-
                    Updated message text content.
      responses:
        '200':
          description: Message updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteMessage
      summary: Delete a message
      description: >-
        Permanently deletes a chat message from a conversation.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/messageIdParam'
      responses:
        '204':
          description: Message deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/pushedMessages:
    post:
      operationId: createAutomatedMessage
      summary: Send an automated message
      description: >-
        Creates and sends an automated message to a visitor. Automated
        messages can be used for proactive engagement, welcome messages,
        or scripted bot responses.
      tags:
        - Automated Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAutomatedMessage'
      responses:
        '200':
          description: Automated message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomatedMessageResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/pushedMessages/{pushedMessageId}:
    get:
      operationId: getAutomatedMessage
      summary: Get an automated message
      description: >-
        Retrieves the details of a specific automated message by its
        unique identifier.
      tags:
        - Automated Messages
      parameters:
        - name: pushedMessageId
          in: path
          required: true
          description: >-
            Unique identifier of the automated message.
          schema:
            type: string
      responses:
        '200':
          description: Automated message retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomatedMessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Automated message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateAutomatedMessage
      summary: Update an automated message
      description: >-
        Updates the content of an existing automated message.
      tags:
        - Automated Messages
      parameters:
        - name: pushedMessageId
          in: path
          required: true
          description: >-
            Unique identifier of the automated message.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAutomatedMessage'
      responses:
        '200':
          description: Automated message updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomatedMessageResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Automated message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteAutomatedMessage
      summary: Delete an automated message
      description: >-
        Permanently deletes an automated message.
      tags:
        - Automated Messages
      parameters:
        - name: pushedMessageId
          in: path
          required: true
          description: >-
            Unique identifier of the automated message.
          schema:
            type: string
      responses:
        '204':
          description: Automated message deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Automated message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/agentOnlinePing:
    post:
      operationId: setAgentOnline
      summary: Set agent status to online
      description: >-
        Sets an agent's status to online for approximately 2-3 minutes.
        This endpoint should be pinged every minute for as long as the
        agent needs to be considered available for conversations.
      tags:
        - Agent Status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
              properties:
                agentId:
                  type: string
                  description: >-
                    Unique identifier of the agent to set online.
                receivedFrom:
                  type: string
                  description: >-
                    Source identifier for the agent's connection.
      responses:
        '204':
          description: Agent status set to online successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Brevo API key passed in the api-key request header for
        authentication.
  parameters:
    messageIdParam:
      name: messageId
      in: path
      required: true
      description: >-
        Unique identifier of the chat message.
      schema:
        type: string
  schemas:
    SendMessage:
      type: object
      required:
        - visitorId
        - text
      properties:
        visitorId:
          type: string
          description: >-
            Unique identifier of the visitor to send the message to.
        text:
          type: string
          description: >-
            Text content of the message.
        agentId:
          type: string
          description: >-
            Unique identifier of the agent sending the message.
        agentName:
          type: string
          description: >-
            Display name of the agent.
    MessageResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the message.
        type:
          type: string
          description: >-
            Type of the message sender.
          enum:
            - agent
            - visitor
            - bot
        text:
          type: string
          description: >-
            Text content of the message.
        visitorId:
          type: string
          description: >-
            Unique identifier of the visitor.
        agentId:
          type: string
          description: >-
            Unique identifier of the agent if applicable.
        agentName:
          type: string
          description: >-
            Display name of the agent if applicable.
        createdAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the message was created.
    CreateAutomatedMessage:
      type: object
      required:
        - visitorId
        - text
      properties:
        visitorId:
          type: string
          description: >-
            Unique identifier of the visitor to send the automated
            message to.
        text:
          type: string
          description: >-
            Text content of the automated message.
        agentId:
          type: string
          description: >-
            Unique identifier of the agent to attribute the message to.
        groupId:
          type: string
          description: >-
            Group identifier for routing the conversation.
    UpdateAutomatedMessage:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: >-
            Updated text content of the automated message.
    AutomatedMessageResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the automated message.
        visitorId:
          type: string
          description: >-
            Unique identifier of the visitor.
        text:
          type: string
          description: >-
            Text content of the automated message.
        agentId:
          type: string
          description: >-
            Agent attributed to the message.
        createdAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the message was created.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Error code identifying the type of error.
        message:
          type: string
          description: >-
            Human-readable description of the error.