Контакты

Доступ только для чтения к контактам проекта. Контакты — это люди, которые обращались к вам через разные каналы.

Список контактов

Список контактов (курсорная пагинация).

Ответ

200Успех

{
  "results": [
    {
      "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e",
      "display_name": "Jane Doe",
      "notes": "VIP customer",
      "metadata": { "plan": "gold" },
      "is_blocked": false,
      "created_at": "2026-06-01T09:00:00+00:00",
      "updated_at": "2026-07-01T10:40:00+00:00"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Поддерживает cursor и limit (по умолчанию 50, максимум 100).

Получить контакт

Получить один контакт по id.

Ответы

200Успех

{
  "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e",
  "display_name": "Jane Doe",
  "notes": "VIP customer",
  "metadata": { "plan": "gold" },
  "is_blocked": false,
  "created_at": "2026-06-01T09:00:00+00:00",
  "updated_at": "2026-07-01T10:40:00+00:00"
}

404Не найдено

{ "detail": "contact_not_found" }

Объект контакта

id, display_name.
notes — произвольные заметки оператора.
metadata — произвольный JSON, привязанный к контакту.
is_blocked — заблокирован ли контакт.
created_at, updated_at — ISO-8601.

Создать контакт

Создаёт контакт и, при необходимости, адрес, по которому он доступен. Требуется право write.

curl -X POST https://chatonio.com/api/v1/contacts/ \
  -H "Authorization: Bearer csk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Jane Roe",
    "identities": [
      { "channel_id": "id-вашего-email-канала", "address": "jane@acme.com" }
    ]
  }'

Идентификаторы — только email

Контакт доступен через идентификатор — канал плюс адрес, которым пользуется клиент. Сейчас создать его можно только для email-канала, потому что адрес электронной почты можно знать заранее. Идентификаторы Telegram, Viber и WhatsApp выдаются этими платформами, когда клиент пишет первым, а идентификатор веб-чата — это сессия браузера, поэтому придуманный вами адрес не дойдёт ни до кого. Для них вернётся 400 identity_not_supported_for_channel_type.

Контакт без идентификатора создать можно — это удобно для зеркалирования CRM, — но написать ему нельзя, и он не будет сопоставлен, когда этот человек напишет сам: входящие сообщения сопоставляются по идентификатору. Если адрес уже принадлежит другому контакту, вернётся 409 identity_already_exists с его указанием, а не вторая полупустая запись.

Изменить контакт

PATCH /api/v1/contacts/{id}/ меняет display_name, notes, metadata и tag_ids. Поля, которые вы не передали, остаются без изменений; tag_ids заменяет весь набор, а [] очищает его.

POST /api/v1/contacts/{id}/tags/ с телом {"tag_id": "…"} добавляет тег, а DELETE /api/v1/contacts/{id}/tags/{tag_id}/ — удаляет. Список тегов проекта — GET /api/v1/tags/. Тег из другого проекта будет отклонён, а не проигнорирован.

Другие диалоги этого контакта

GET /api/v1/contacts/{id}/conversations/ возвращает все диалоги этого человека по всем каналам, начиная с самых свежих, — удобно, чтобы показывать историю рядом с обращением в вашей собственной системе.

Контакты