Работа с контактами

Контакт — сущность, которая связывает пользователя и клиента. Это «карточка контакта», где указан ответственный за клиента менеджер и хранятся контактные данные клиента: номер телефона для связи в WhatsApp, ID в Telegram, юзернейм в Instagram.

Добавление и обновление списка контактов

Чтобы добавить или обновить список контактов, отправьте запрос:

 POST https://api.wazzup24.com/v3/contacts

В одном запросе можно указать не более 100 контактов.

Параметр

Обязательные параметры отмечены «звездочкой»

Тип Описание
id* String ID контакта в CRM-системе. Не более 100 символов
responsibleUserId* String ID ответственного пользователя. Не более 100 символов.
Заполните это поле, чтобы диалог отобразился в окне чата Wazzup у ответственного за клиента пользователя
name* String Имя контакта. Не более 200 символов
contactData* Array Массив объектов с контактными данными клиента
contactData.chatType* String Тип чата. Доступные значения:

  • whatsapp — для индивидуальных чатов в WhatsApp,
  • whatsgroup — для групповых чатов в WhatsApp,
  • instagram — для чатов в Инсте,
  • telegram — для индивидуальных чатов в Telegram,
  • telegroup — для групповых чатов в Telegram,
  • vk — для чатов Вконтакте,
  • avito — для чатов Авито
contactData.chatId* String ID чата (аккаунт контакта в мессенджере):

  • для whatsapp — только цифры, без пробелов и специальных символов в формате 79011112233,
  • для instagram — аккаунт без @ вначале,
  • для whatsgroup — приходит в вебхуках входящих сообщений,
  • для telegram — приходит в вебхуках входящих сообщений и в ответ на запрос при отправке исходящего с параметрами phone или username. Об этих параметрах пишем далее,
  • для avito и vk приходит в вебхуках входящих сообщений
contactData.username String Только для Telegram.

Имя пользователя в Telegram, без @ в начале. Можно использовать при отправке сообщений через Telegram, если не известен chatId

contactData.phone String Только для Telegram.

Телефон контакта в международном формате, без + и иных символов: только цифры с корректным кодом страны. Может использоваться при отправке сообщений через Telegram, если не известен chatId

uri String Ссылка на контакт в CRM. Не более 200 символов.
Если указано, то пользователь увидит в «чемодане» кнопку, ведущую на страницу контакта в CRM
Пример запроса
fetch("https://api.wazzup24.com/v3/contacts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {apiKey}",
  },
  body: [
{
        "id": "1",
        "responsibleUserId": "1",
        "name": "3301",
        "contactData": [
            {
                "chatType": "whatsapp",
                "chatId": "79991114433"
            }
        ],
        "uri": "https://link-to-contact-in-crm.com"
    },
    {
        "id": "2",
        "responsibleUserId": "1",
        "name": "3302",
        "contactData": [
            {
                "chatType": "whatsapp",
                "chatId": "79884447788"
            }
        ]
    }
]
Ошибки

Помимо общих ошибок для всех роутов еще возможны:

Ошибка Описание
INVALID_CONTACTS_DATA Тело запроса пустое или какие-то из переданных полей невалидны
TOO_MACH_ENTITIES Превышен лимит в 100 сущностей на один запрос

 HTTP/1.1 400 Bad Request
{
"error": "INVALID_CONTACTS_DATA",
"description": "One or more of provided contacts data are not valid."
"data": [
{
index: 12,
fields: [
"responsibleUserId",
]
}
]
}

 HTTP/1.1 400 Bad Request
{
"error": "TOO_MACH_ENTITIES",
"description": "Too mach entities per request.",
"data": {
"count": 123,
"limit": 100,
}
}

Получение списка контактов

Чтобы получить список контактов, необходимо вызвать:

 GET https://api.wazzup24.com/v3/contacts?offset=

За один запрос можно получить до 100 записей с учетом offset c сортировкой по id по возрастанию (ASC).

offset — Смещение по пагинации, целое неотрицательное число.

Ответ

Данные результата запроса придут в виде массива объектов со следующими параметрами:

Параметр Тип Описание
count Number Общее количество контактов
data Object Массив с данными о контакте
data.id String ID контакта в CRM-системе. Не более 100 символов
data.responsibleUserId String ID ответственного пользователя. Не более 100 символов
data.name String Имя контакта. Не более 200 символов
data.contactData Object Массив объектов с контактными данными контакта, который содержит:
chatType — string,
chatId — string
data.uri String Ссылка на контакт в CRM. Не более 200 символов.
Если указано, то пользователь видит в «чемодане» кнопку, ведущую на страницу контакта в CRM

Получение информации об отдельном контакте

Чтобы получить информацию о загруженном из CRM в Wazzup отдельном контакте, необходимо вызвать:

 GET https://api.wazzup24.com/v3/contacts/{id контакта}
Пример запроса
 curl --location --request GET 'https://api.wazzup24.com/v3/contacts/111-2e0df379-0e3c-470f-9b36' \
--header 'Authorization: Bearer c8cf904467023482f909520d454368d27'
Ответ

Ответ придет в виде объекта со следующими параметрами:

Параметр Тип Описание
id String ID контакта в CRM-системе. Не более 100 символов
responsibleUserId String ID ответственного пользователя. Не более 100 символов
name String Имя контакта. Не более 200 символов
contactData Object Массив объектов с контактными данными контакта, который содержит:
chatType — string,
chatId — string
uri String Ссылка на контакт в CRM. Не более 200 символов.Если указано, то пользователь видит в «чемодане» кнопку, ведущую на страницу контакта в CRM

Удаление одного контакта

Для удаления контакта необходимо вызвать:

 DELETE https://api.wazzup24.com/v3/contacts/{id контакта}

Если в общем чате есть диалог с этим контактом — он там останется.

Пример запроса
 curl --location --request DELETE 'https://api.wazzup24.com/v3/contacts/111-2e0df379-0e3c-470f-9b36' \
--header 'Authorization: Basic c8cf90444023482f909520d454368d27'
Ошибки

Удаление нескольких контактов

Чтобы удалить список контактов, необходимо вызвать:

 PATCH https://api.wazzup24.com/v3/contacts/bulk_delete

В теле запроса передайте массив ID контактов, которых нужно удалить. При успешном удалении вернется 200 ОК и пустой массив. Если в запросе на удаление были указаны контакты, которых нет в Wazzup, то их ID вернутся в ответе в виде массива.

Пример запроса
fetch("https://api.wazzup24.com/v3/contacts/bulk_delete", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {apiKey}",
  },
  body: [
    "contact-id-123",
    "contact-id-456",
  ]
});