brevo Automated Messages API

openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status Automated Messages API
  description: The Brevo Contacts API provides programmatic access to contact management features including creating, updating, and deleting contacts. Developers can organize contacts into lists, apply attributes and tags, import contacts in bulk, and build audience segments for targeted campaigns. The API also supports managing folders, contact attributes, and custom fields to structure contact data according to business needs.
  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:
    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.
    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.
    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.
  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 Contacts Documentation
  url: https://developers.brevo.com/docs/how-it-works