Avito Messenger API

openapi: 3.2.0
info:
  contact:
    email: supportautoload@avito.ru
  description: 'API для взаимодействия с иерархией аккаунтов в Авито

    **Авито API для бизнеса предоставляется согласно [Условиям использования](https://www.avito.ru/legal/pro_tools/public-api).**

    '
  title: Иерархия Аккаунтов Access Messenger API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- description: 'API для интеграции между мессенджером Авито и сторонней системой в обе стороны.

    '
  name: Messenger
  x-displayName: Messenger API
paths:
  /messenger/v1/accounts/{user_id}/chats/{chat_id}/messages:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    post:
      description: 'На данный момент можно отправить только текстовое сообщение

        '
      operationId: postSendMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sendMessageRequestBody'
        description: Отправление сообщения
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  content:
                    properties:
                      text:
                        example: привет
                        type: string
                    type: object
                  created:
                    example: 1563202313
                    type: integer
                  direction:
                    example: out
                    type: string
                  id:
                    example: bdcc5bac2d00345f1cc66fa657813958
                    type: string
                  type:
                    example: text
                    type: string
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              content:
                text: привет!
              created: 1563202313
              direction: in
              id: bdcc5bac2d00345f1cc66fa657813958
              type: text
      security:
      - AuthorizationCode:
        - messenger:write
      - ClientCredentials: []
      summary: Отправка сообщения
      tags:
      - Messenger
  /messenger/v1/accounts/{user_id}/chats/{chat_id}/messages/image:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    post:
      description: 'Метод используется для отправки сообщения с изображением.


        Для отправки сообщения с изображением необходимо передать в запросе id изображения, полученного после загрузки.

        '
      operationId: postSendImageMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sendImageMessageRequestBody'
        description: Вложение с изображением
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  author_id:
                    example: 9623532
                    type: integer
                  content:
                    properties:
                      image:
                        properties:
                          sizes:
                            additionalProperties:
                              type: string
                            example:
                              1280x960: https://example.hosts.ru/image_1280_960.png
                              140x105: https://example.hosts.ru/image_140_105.png
                              32x32: https://example.hosts.ru/image_32_32.png
                            type: object
                        type: object
                    type: object
                  created:
                    example: 1563202313
                    type: integer
                  direction:
                    example: out
                    type: string
                  id:
                    example: bdcc5bac2d00345f1cc66fa657813958
                    type: string
                  type:
                    example: image
                    type: string
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              author_id: 9623532,
              content:
                image:
                  sizes:
                    1280x960: https://example.hosts.ru/image_1280_960.png
                    140x105: https://example.hosts.ru/image_140_105.png
                    32x32: https://example.hosts.ru/image_32_32.png
              created: 1563202313
              direction: out
              id: bdcc5bac2d00345f1cc66fa657813958
              type: image
      security:
      - AuthorizationCode:
        - messenger:write
      - ClientCredentials: []
      summary: Отправка сообщения с изображением
      tags:
      - Messenger
  /messenger/v1/accounts/{user_id}/chats/{chat_id}/messages/{message_id}:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    - $ref: '#/components/parameters/messageId'
    post:
      description: 'Сообщение не пропадает из истории, а меняет свой тип на deleted.

        Удалять сообщения можно не позднее часа с момента их отправки.

        '
      operationId: deleteMessage
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:write
      - ClientCredentials: []
      summary: Удаление сообщения
      tags:
      - Messenger
  /messenger/v1/accounts/{user_id}/chats/{chat_id}/read:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    post:
      description: 'После успешного получения списка сообщений необходимо вызвать этот метод для того, чтобы чат стал прочитанным.

        '
      operationId: chatRead
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ok:
                    example: true
                    type: boolean
                type: object
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Прочитать чат
      tags:
      - Messenger
  /messenger/v1/accounts/{user_id}/getVoiceFiles:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/voiceIds'
    get:
      description: "Метод используется для получения ссылки на файл с голосовым сообщением по идентификатору voice_id, получаемому из тела сообщения с типом voice.\n\nОсобенности работы с голосовыми сообщениями:\n- Голосовые сообщения Авито используют кодек **[opus](https://ru.wikipedia.org/wiki/Opus_(%D0%BA%D0%BE%D0%B4%D0%B5%D0%BA))** внутри **.mp4** контейнера; \n- Ссылка на голосовое сообщение доступна в течение **одного часа** с момента запроса. Попытка получить файл по ссылке спустя это время приведёт к ошибке. Для восстановления доступа необходимо получить новую ссылку на файл;\n- Как и с обычными сообщениями, получение ссылки на файл доступно только для пользователей, находящихся в беседе, где голосовое сообщение было отправлено;\n"
      operationId: getVoiceFiles
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceFiles'
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Получение голосовых сообщений
      tags:
      - Messenger
  /messenger/v1/accounts/{user_id}/uploadImages:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    post:
      description: 'Метод используется для загрузки изображений в формате JPEG, HEIC, GIF, BMP или PNG.


        Особенности работы с загрузкой изображений:

        - Метод поддерживает только одиночные изображения; для загрузки нескольких картинок необходимо сделать несколько запросов;

        - Максимальный размер файла — 24 МБ;

        - Максимальное разрешение — 75 мегапиксилей;

        '
      operationId: uploadImages
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                uploadfile[]:
                  format: binary
                  type: string
              required:
              - uploadfile[]
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  additionalProperties:
                    type: string
                  type: object
                example:
                  12345.12345abcdefghijklm:
                    1280x960: https://example.hosts.ru/image_1280_960.png
                    140x105: https://example.hosts.ru/image_140_105.png
                    32x32: https://example.hosts.ru/image_32_32.png
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              12345.12345abcdefghijklm:
                1280x960: https://example.hosts.ru/image_1280_960.png
                140x105: https://example.hosts.ru/image_140_105.png
                32x32: https://example.hosts.ru/image_32_32.png
      security:
      - AuthorizationCode:
        - messenger:write
      - ClientCredentials: []
      summary: Загрузка изображений
      tags:
      - Messenger
  /messenger/v1/subscriptions:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Получение списка подписок

        '
      operationId: getSubscriptions
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  subscriptions:
                    items:
                      properties:
                        url:
                          example: http://abc
                          type: string
                        version:
                          description: Версия метода, через который вебхук добавлен. Влияет на формат получаемых данных
                          example: '3'
                          type: string
                      required:
                      - url
                      - version
                      type: object
                    type: array
                required:
                - subscriptions
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              ok: true
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Получение подписок (webhooks)
      tags:
      - Messenger
  /messenger/v1/webhook/unsubscribe:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Отключение уведомлений

        '
      operationId: postWebhookUnsubscribe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookSubscribeRequestBody'
        description: Url, на который необходимо перестать слать уведомления
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ok:
                    example: true
                    type: boolean
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              ok: true
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Отключение уведомлений (webhooks)
      tags:
      - Messenger
      x-code-samples:
      - lang: PHP
        source: "$ch = curl_init(\"https://api.avito.ru/messenger/v1/webhook/unsubscribe\");\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n\t\"Content-Type: application/json\",\n\t\"Authorization: Bearer <TOKEN>\",\n]);\ncurl_setopt($ch, CURLOPT_POST, true);\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([\n\t\"url\" => \"https://test.test\",\n], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));\n\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$result = curl_exec($ch);\ncurl_close($ch);"
  /messenger/v2/accounts/{user_id}/blacklist:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    post:
      description: 'Добавление пользователя в blacklist

        '
      operationId: postBlacklistV2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addBlacklistRequestBody'
        description: Добавление пользователя в blacklist
      responses:
        '200':
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:write
      - ClientCredentials: []
      summary: Добавление пользователя в blacklist
      tags:
      - Messenger
  /messenger/v2/accounts/{user_id}/chats:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/itemIds'
    - $ref: '#/components/parameters/unreadOnly'
    - $ref: '#/components/parameters/chatTypes'
    - $ref: '#/components/parameters/limit'
    - $ref: '#/components/parameters/offset'
    get:
      description: 'Возвращает список чатов

        '
      operationId: getChatsV2
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chats'
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Получение информации по чатам
      tags:
      - Messenger
  /messenger/v2/accounts/{user_id}/chats/{chat_id}:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    get:
      description: 'Возвращает данные чата и последнее сообщение в нем

        '
      operationId: getChatByIdV2
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Получение информации по чату
      tags:
      - Messenger
  /messenger/v3/accounts/{user_id}/chats/{chat_id}/messages/:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/chatId'
    - $ref: '#/components/parameters/limit'
    - $ref: '#/components/parameters/offset'
    get:
      description: 'Получение списка сообщений.  **Не помечает чат прочитанным.**

        После успешного получения списка сообщений необходимо вызвать [метод](https://api.avito.ru/docs/api.html#operation/chatRead), который сделает сообщения прочитанными.

        Для получения новых сообщений в реальном времени используйте [webhooks](https://api.avito.ru/docs/api.html#operation/postWebhookV3)

        '
      operationId: getMessagesV3
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Messages'
          description: Успешный ответ
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Получение списка сообщений V3
      tags:
      - Messenger
  /messenger/v3/webhook:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: "Включение webhook-уведомлений. \n\nСхему JSON приходящего в webhook сообщения можно увидеть в примерах ответов.\n\nПосле регистрации url'а для получения веб-хуков, убедитесь, что он доступен, работает и возвращает статус 200 ОК соблюдая timeout 2s,\nнапример, выполнив запрос:\n\ncurl --connect-timeout 2 <url-вашего-вебхука> -i -d '{}'\n"
      operationId: postWebhookV3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookSubscribeRequestBody'
        description: Url на который будут отправляться уведомления
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ok:
                    example: true
                    type: boolean
                type: object
          description: Успешный ответ
          x-examples:
            application/json:
              ok: true
        '201':
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: Уникальный идентификатор сообщения webhooks
                    example: abc
                    type: string
                  payload:
                    $ref: '#/components/schemas/PayloadStruct'
                  timestamp:
                    description: Unix-timestamp времени отправки сообщения webhooks
                    example: 123
                    type: integer
                  version:
                    description: Версия webhooks
                    example: v1.1
                    type: string
                type: object
          description: JSON сообщения, который будет приходить в webhook
          x-examples:
            application/json:
              ok: true
      security:
      - AuthorizationCode:
        - messenger:read
      - ClientCredentials: []
      summary: Включение уведомлений V3 (webhooks)
      tags:
      - Messenger
      x-code-samples:
      - lang: PHP
        source: "$ch = curl_init(\"https://api.avito.ru/messenger/v3/webhook\");\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n\t\"Content-Type: application/json\",\n\t\"Authorization: Bearer <TOKEN>\",\n]);\ncurl_setopt($ch, CURLOPT_POST, true);\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([\n\t\"url\" => \"https://test.test\",\n], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));\n\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$result = curl_exec($ch);\ncurl_close($ch);"
components:
  schemas:
    Chats:
      properties:
        chats:
          description: Список чатов
          items:
            $ref: '#/components/schemas/Chat'
          type: array
      type: object
    sendImageMessageRequestBody:
      properties:
        image_id:
          description: Идентификатор загруженного изображения
          type: string
      required:
      - image_id
      type: object
    MessageQuote:
      description: цитируемое сообщение
      properties:
        author_id:
          example: 94235311
          format: int64
          type: integer
        content:
          $ref: '#/components/schemas/MessageContent'
        created:
          example: 1571654040
          format: int64
          type: integer
        id:
          type: string
        type:
          enum:
          - text
          - image
          - link
          - item
          - location
          - call
          - deleted
          - voice
          - system
          type: string
      type: object
    WebhookMessage:
      properties:
        author_id:
          description: ID пользователя, отправившего сообщение
          example: 123
          type: integer
        chat_id:
          description: Уникальный идентификатор чата, куда отправлено сообщение
          example: abc
          type: string
        chat_type:
          description: Тип чата (u2i - чат по объявлению, u2u - чат по профилю пользователя, a2u - чат по профилю пользователя c Авито)
          enum:
          - u2i
          - u2u
          - a2u
          example: u2i
          type: string
        content:
          $ref: '#/components/schemas/MessageContent'
        created:
          description: Unix-timestamp времени создания сообщения
          example: 123
          type: integer
        id:
          description: Уникальный идентификатор сообщения
          example: abc
          type: string
        item_id:
          description: ID объявления, актуально только для чатов с типом u2i
          example: 123
          type:
          - integer
          - 'null'
        published_at:
          description: Время публикации сообщения в формате RFC3339 в UTC
          example: '1973-03-04T13:33:09Z'
          type: string
        read:
          description: Unix-timestamp времени прочтения, если сообщение уже прочитано
          example: 123
          type:
          - integer
          - 'null'
        type:
          description: Тип сообщения
          enum:
          - text
          - image
          - system
          - item
          - call
          - link
          - location
          - deleted
          - appCall
          - file
          - video
          - voice
          example: text
          type: string
        user_id:
          description: ID пользователя, получившего сообщение. Это всегда аккаунт, на который зарегистрирован вебхук
          example: 123
          type: integer
      type: object
    Chat:
      properties:
        context:
          description: Сопутствующая к чату информация, несвязанная с мессенджером напрямую
          properties:
            type:
              description: Тип контекста, определяет значение и смысл других полей в объекте контекста
              example: item
              type: string
            value:
              properties:
                id:
                  description: ID объявления
                  example: 1768287444
                  format: int32
                  type: integer
                images:
                  description: Изображения с карточки объявления
                  properties:
                    count:
                      description: Число изображений
                      example: 4
                      format: int32
                      type: integer
                    main:
                      properties:
                        140x105:
                          description: Изображение в формате 140х105
                          example: https://01-img-staging-proxy.k.avito.ru/140x105/5815183159.jpg
                          type: string
                      type: object
                  type: object
                price_string:
                  description: Цена в объявлении, с указанием валюты
                  example: 300 000 ₽
                  type: string
                status_id:
                  description: Статус объявления, например 20 — объявление удалено
                  example: 10
                  format: int32
                  type: integer
                title:
                  example: Mazda 3 2008
                  type: string
                url:
                  description: Ссылка на объявление
                  example: https://avito.ru/moskva/avtomobili/mazda_3_2008_1768287444
                  type: string
                user_id:
                  description: ID автора объявления
                  example: 141906442
                  format: int32
                  type: integer
              type: object
          type: object
        created:
          description: Unix-timestamp времени создания чата
          example: 1571412836
          format: int32
          type: integer
        id:
          description: Уникальный идентификтор чата
          type: string
        last_message:
          properties:
            author_id:
              description: Ссылка на профиль пользователя в Авито
              example: 94235311
              format: int32
              type: integer
            content:
              $ref: '#/components/schemas/MessageContent'
            created:
              description: Unix-timestamp времени отправки сообщения
              example: 1571654040
              format: int32
              type: integer
            direction:
              description: '"in" для входящих сообщений, "out" для исходящих'
              example: out
              type: string
            id:
              description: Уникальный идентификатор сообщения
              type: string
            type:
              description: Тип контента в сообщений
              example: link
              type: string
          type: object
        updated:
          description: Unix-timestamp времени последнего обновления чата
          example: 1571654040
          format: int32
          type: integer
        users:
          items:
            properties:
              id:
                description: Уникальный ID пользователя. Обратите внимание на хэширование
                example: 94235311
                format: int32
                type: integer
              name:
                description: Имя пользователя
                example: Guldan
                type: string
              public_user_profile:
                properties:
                  avatar:
                    description: Фотография пользователя (аватар)
                    properties:
                      default:
                        example: https://www.avito.st/stub_avatars/_/14_256x256.png
                        type: string
                      images:
                        properties:
                          128x128:
                            description: Аватар в формате 128х128
                            example: https://www.avito.st/stub_avatars/_/14_128x128.png
                            type: string
                          192x192:
                            description: Аватар в формате 192х192
                            example: https://www.avito.st/stub_avatars/_/14_192x192.png
                            type: string
                          24x24:
                            description: Аватар в формате 24х24
                            example: https://www.avito.st/stub_avatars/_/14_24x24.png
                            type: string
                          256x256:
                            description: Аватар в формате 256х256
                            example: https://www.avito.st/stub_avatars/_/14_256x256.png
                            type: string
                          36x36:
                            description: Аватар в формате 36х36
                            example: https://www.avito.st/stub_avatars/_/14_36x36.png
                            type: string
                          48x48:
                            description: Аватар в формате 48х48
                            example: https://www.avito.st/stub_avatars/_/14_48x48.png
                            type: string
                          64x64:
                            description: Аватар в формате 64х64
                            example: https://www.avito.st/stub_avatars/_/14_64x64.png
                            type: string
                          72x72:
                            description: Аватар в формате 72х72
                            example: https://www.avito.st/stub_avatars/_/14_72x72.png
                            type: string
                          96x96:
                            description: Аватар в формате 96х96
                            example: https://www.avito.st/stub_avatars/_/14_96x96.png
                            type: string
                        type: object
                    type: object
                  item_id:
                    description: ID объявления, выложенного пользователем
                    example: 1768287444
                    format: int32
                    type: integer
                  url:
                    description: Ссылка на профиль пользователя в Авито
                    example: https://avito.ru/user/db65c00c946dc404e11f14755465453b/profile
                    type: string
                  user_id:
                    description: Уникальный ID пользователя. Обратите внимание на хэширование
                    example: 94235311
                    format: int32
                    type: integer
                type: object
        

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/avito/refs/heads/main/openapi/avito-messenger-api-openapi.yml