brevo Automated Messages API

openapi: 3.2.0
info:
  title: Brevo Conversations Automated Messages 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/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: Automated Messages
  description: Create, manage, and retrieve automated messages pushed to visitors.
paths:
  /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'
components:
  schemas:
    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.
    UpdateAutomatedMessage:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: Updated text content of the automated message.
    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.
    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.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Brevo API key passed in the api-key request header for authentication.
externalDocs:
  description: Brevo Conversations Documentation
  url: https://developers.brevo.com/docs/getting-started-with-conversations-api