Contacts

/v1/contacts

С помощью узла contacts вы можете управлять пользователями WhatsApp в своей базе данных, проверяя их подлинность перед отправкой сообщений, а также проверяя их личность с помощью хэшей.

Узел contacts позволяет:

• проверить, связан ли номер телефона в вашей базе данных с действительным аккаунтом WhatsApp (чтобы пользователю можно было отправить сообщение, параметр status должен иметь значение valid);
• получить ID WhatsApp для номера телефона (эти ID нужны для отправки сообщений и уведомлений пользователям).

Прежде чем начать

Вы должны предоставить своим клиентам возможность согласиться на получение сообщений в WhatsApp от вашей компании или отказаться от этого. Процедурой получения согласия управляете вы сами. Когда клиент даст согласие, воспользуйтесь узлом contacts, чтобы проверить зарегистрированный номер. Дополнительную информацию см. в статье Получение согласия на отправку сообщений в WhatsApp.

Ограничения

• С помощью этой конечной точки можно проверять, связан ли номер телефона в базе данных компании с действительным аккаунтом WhatsApp.
• Количество вызовов не должно превышать количество сообщений, которые отправляет номер телефона.

Обеспечение соблюдения правил использования

Если компания использует конечную точку не по назначению, будут приняты следующие меры:

• если мы подозреваем, что вы нарушаете правила использования конечной точки, все администраторы компании, указанные в Business Manager, получат первичное предупреждение по электронной почте;
• после этого у компании будет семь дней на то, чтобы устранить проблемы;
• если через семь дней вызовы не будут исправлены, номер телефона будет отключен навсегда.

Рекомендации

Мы рекомендуем проверять контакты перед отправкой сообщений. Однако для ответа на входящее сообщение от клиента проверять контакты не нужно: ответить можно сразу же, используя полученный wa_id. Это не влечет за собой дополнительных расходов, так как результаты кэшируются.

Создание

Перед отправкой сообщений пользователям, которые согласились их принимать, отправьте запрос POST к конечной точке /v1/contacts, чтобы создать запрос на проверку пользователя аккаунта WhatsApp. Добавьте в вызов список проверяемых номеров телефонов.

Пример

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

В ответе будут указаны текущие статусы (status) запрошенных номеров и соответствующие ID WhatsApp (wa_id):

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

Сохраните ID WhatsApp, относящиеся к номерам, для которых параметр status имеет значение valid. Действительными считаются пользователи, у которых есть аккаунт WhatsApp. Используйте ID WhatsApp для отправки сообщений и уведомлений.

Регулярно повторяйте эти действия, чтобы список пользователей оставался актуальным. Результаты хранятся в кэше базы данных клиента локального WhatsApp Business API в течение 7 дней.

Параметры

В вызовах POST к узлу /v1/contacts поддерживаются следующие параметры:

Границы контекста

С этим узлом связаны следующие границы контекста:

Блокировка

Параметр blocking может принимать два значения: no_wait и wait. Если значение параметра blocking в запросе не задано, по умолчанию используется no_wait.

Параметр blocking определяет тип запроса: синхронный или асинхронный. Их различие состоит в том, что ответ на синхронный запрос возвращается после завершения обработки.

Форматы номеров телефонов

В запросах к contacts можно указывать номера телефонов в любом стандартном формате.

Посмотрите, как это работает, на примере клиента локального WhatsApp Business API, зарегистрированного с индийским номером телефона (код страны +91):

Возвращаемые поля

Полезные данные в ответе от узла contacts содержат тот же массив номеров телефонов, который передается в запросе, со свойствами input, status и wa_id.

Вместе со статусом обработки (processing) должно выдаваться сообщение HTTP 200 OK.

Если сообщение с шаблоном отправляется на номер телефона, не имеющий аккаунта WhatsApp, вы получите сообщение об ошибке Недействительный пользователь с кодом ошибки 1013.

Информацию о других ошибках в ответе см. в статье Сообщения об ошибках и коды статусов.

Блокировка контактов

Блокировку можно рассматривать как защитную функцию, которая не позволит злоумышленникам продолжать вредоносные действия. Заблокировать контакт можно, если он отправил вам сообщение в течение последних 24 часов.

Пример

Отправьте вызов API к узлу /v1/contacts/{phone_number}/block, указав причину блокировки другого аккаунта WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

В случае успеха ответ будет содержать статус HTTP 200, а объекта errors не будет.

В случае ошибки ответ выглядит следующим образом:

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Параметры

В вызовах POST к узлу /v1/contacts/{phone_number}/block поддерживаются следующие параметры:

Разблокировка контактов

Выполните этот вызов, чтобы разблокировать контакт.

Пример

Отправьте вызов API к /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

В случае успеха ответ будет содержать статус HTTP 200, а объекта errors не будет.

В случае ошибки ответ выглядит следующим образом:

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

Параметры

В вызовах POST к узлу /v1/contacts/{phone_number}/unblock поддерживаются следующие параметры:

Список блокировки

Вот как можно получить список своих заблокированных контактов.

Пример

Отправьте вызов API к /v1/contacts/blocklist, чтобы получить разбитый на страницы список своих заблокированных контактов.

GET /v1/contacts/blocklist?limit=10&offset=0

Вы получите ответ с указанием страницы в списке блокировки вместе с информацией о разбивке на страницы.

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

Параметры

В вызовах GET к узлу /v1/contacts/blocklist поддерживаются следующие параметры:

Отчеты

Отчеты предоставляют важнейшие сигналы для выработки превентивных решений в отношении злоумышленников. Пожаловаться на контакт можно, если он отправил вам сообщение в течение последних 24 часов.

Пример

Отправьте вызов API к узлу /v1/contacts/{phone_number}/report, указав причину блокировки другого аккаунта WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

В случае успеха ответ будет содержать статус HTTP 200, а объекта errors не будет.

В случае ошибки ответ выглядит следующим образом:

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Параметры

В вызовах POST к узлу /v1/contacts/{phone_number}/report поддерживаются следующие параметры: