Быстрый старт для разработчиков с использованием WhatsApp API

Используйте это руководство, чтобы добавить функцию обмена сообщениями WhatsApp в ChatArchitect в любой сторонний сервис. Оно охватывает учетные данные, исходящие сообщения, шаблоны, статусы доставки, входящие сообщения и базовый сценарий тестирования.

Реализуйте подключение WhatsApp API к этому коду с помощью ChatArchitect, используя официальное руководство: https://support.chatarchitect.com/books/whatsapp-for-partners/page/whatsapp-api-quick-start-for-developers. Сначала изучите существующую архитектуру приложения, затем добавьте обработку учетных данных на стороне сервера, отправку сообщений, загрузку шаблонов, обработку веб-хуков для статусов и входящих сообщений, а также минимальный пользовательский интерфейс/настройки, необходимые для подключения пользователей.

Что вы построите

К концу этого руководства ваша служба сможет:

• Отправляйте текстовые сообщения WhatsApp и сообщения по утвержденным шаблонам.
• Получайте асинхронные статусы доставки через веб-перехватчик: отправлено, затем не выполнено, отправлено, доставленоили прочитано.
• Получайте входящие сообщения от клиентов через тот же веб-хук.
• Получайте одобренные шаблоны WhatsApp из API ChatArchitect.

Если клиент пишет первым, вы можете ответить без использования шаблона в активном окне службы поддержки. Если же разговор инициирует ваша компания, используйте утвержденный шаблон WhatsApp.

Предварительные требования и квалификация

Клиенту необходимо подключить WhatsApp Business API через службу поддержки ChatArchitect и Meta. После настройки ChatArchitect предоставит:

Оба значения следует хранить на стороне сервера. Не раскрывайте значение APP_SECRET в коде браузера, публичных журналах, конфигурации на стороне клиента или URL-адресах.

Во всех приведенных ниже примерах используется:

Базовый URL API: https://api.chatarchitect.com Аутентификация: Базовая аутентификация с<APP_ID> :<APP_SECRET> Телефон получателя:<recipient_phone> URL веб-перехватчика:<webhook_url>

Используйте телефонные номера в международном формате без знаков +, пробелов или скобок, например, 421233221242.

Быстрый старт: 3 вызова API

Шаг 1 — Зарегистрируйте веб-перехватчик

Зарегистрируйте URL-адрес веб-перехватчика HTTPS для отслеживания статусов доставки и входящих сообщений.

POST https://api.chatarchitect.com/webhook Authorization: Basic base64(<APP_ID> :<APP_SECRET> Content-Type: application/json

Текст запроса:

{ "канал": "whatsapp", "назначение": "<recipient_phone> ", "webhook_separate": "false", "webhook": "<webhook_url> " }

В качестве адресата может быть указан любой номер WhatsApp, привязанный к учетной записи. Веб-хук должен представлять собой HTTPS-адрес, доступный из общедоступного интернета.

Пример использования cURL:

curl -X POST "https://api.chatarchitect.com/webhook" \ -u "<APP_ID> :<APP_SECRET> " \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "<recipient_phone> ", "webhook_separate": "false", "webhook": "<webhook_url> " }'

Шаг 2 — Отправьте текстовое сообщение

Отправьте исходящее сообщение в WhatsApp.

POST https://api.chatarchitect.com/whatsappmessage Authorization: Basic base64(<APP_ID> :<APP_SECRET> Content-Type: application/json

Текст запроса:

{ "канал": "whatsapp", "назначение": "<recipient_phone> ", "payload": { "type": "text", "message": "Привет, Джон, как дела?" } }

Синхронный ответ подтверждает, что сообщение было принято в очередь:

{ "status": "submitted", "messageId": "21110c1d-53e1-42b5-9454-1de9a09d4777" }

Окончательный статус доставки будет сообщен позже через ваш веб-хук.

Пример использования cURL:

curl -X POST "https://api.chatarchitect.com/whatsappmessage" \ -u "<APP_ID> :<APP_SECRET> " \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "<recipient_phone> ", "payload": { "type": "text", "message": "Привет, Джон, как дела?" } }'

Шаг 3 — Получите утвержденные шаблоны

Получите одобренные шаблоны WhatsApp, доступные для подключенного аккаунта.

POST https://api.chatarchitect.com/getHSM Authorization: Basic base64(<APP_ID> :<APP_SECRET> Content-Type: application/json

Текст запроса:

{ "канал": "whatsapp", "назначение": "<recipient_phone> ", "getHSM": "true" }

Фрагмент ответа:

{ "status": "submitted", "templates_status": true, "templates": [ { "appId": "abcf5776-29e0-4e3a-a8ed-09c51e69d53e", "category": "MARKETING", "data": "{{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nHello{{1}}" } ] }

Файл templates.data содержит синтаксис отправки шаблонов. Сохраните или кэшируйте этот список в вашем сервисе, чтобы пользователи могли выбирать одобренные шаблоны.

Пример использования cURL:

curl -X POST "https://api.chatarchitect.com/getHSM" \ -u "<APP_ID> :<APP_SECRET> " \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "<recipient_phone> ", "getHSM": "true" }'

Правила шаблона

Типы шаблонов

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

Категории шаблонов

Категория шаблона влияет на утверждение и ценообразование. Не используйте рекламный контент в UTILITY и OTP .

Утверждение шаблона

Клиенты могут отправлять шаблоны через приложение ChatArchitect или через службу поддержки ChatArchitect. Если вашему сервису требуется более глубокая интеграция, вы можете добавить отправку шаблонов через API в качестве отдельной функции.

Синтаксис отправки шаблона

Шаблон, возвращаемый функцией /getHSM, может выглядеть следующим образом:

{{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nПривет{{1}}

Правила:

• Первый {{...}} содержит обязательный идентификатор шаблона.
• {{1}}, {{2}}, а другие пронумерованные заполнители являются переменными шаблона.
• Значения переменных могут содержать пробелы и несколько слов.
• Значения переменных не должны содержать переносов строк.

Для отправки шаблонного сообщения используйте тот же /whatsappmessage . Отличие от обычного текстового сообщения заключается в значении параметра payload.message.

Пример шаблона для отправки тела сообщения:

{ "канал": "whatsapp", "назначение": "<recipient_phone> ", "payload": { "type": "text", "message": "{{26815959-f5b8-49b4-9b0e-7458d34777cc}}\nПривет, Джон" } }

События веб-перехватчика

События состояния

Ошибки доставки происходят асинхронно. Запрос на отправку может вернуть статус «отправлено», а окончательные сведения об ошибке поступают позже через веб-перехватчик.

Пример события состояния:

{ "app": "aQWPjCAmjav", "timestamp": 1580311136040, "version": 2, "type": "message-event", "payload": { "id": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35", "type": "failed", "destination": "<recipient_phone> ", "payload": { "code": 1008, "reason": "Пользователь не дал согласия и неактивен" } } }

Важные поля:

События входящих сообщений

Пример входящего текстового сообщения:

{ "app": "aQWPjCAmjav", "timestamp": 1580227766370, "version": 2, "type": "message", "payload": { "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c", "source": "<recipient_phone> ", "type": "text", "payload": { "text": "Hi" } } }

Важные поля:

Корреляция

Сохраняйте метаданные исходящих запросов вместе с синхронным messageId. Для обработки веб-хуков также используйте номер телефона клиента и payload.id чтобы сопоставить события статуса и входящие ответы с вашими внутренними записями.

Основные положения политики WhatsApp

При разработке системы обмена сообщениями в вашем сервисе следуйте этим практическим правилам:

• Отправляйте рекламные сообщения только тем клиентам, которые ожидают от компании подобных сообщений.
• Используйте утвержденные шаблоны, когда компания начинает общение.
• Добавьте возможность отписки от рассылки в маркетинговые шаблоны, если это необходимо.
• Избегайте использования списков рассылки, не соответствующих вашим интересам. Высокий уровень жалоб может привести к ограничениям на использование шаблонов или временным лимитам на отправку сообщений.
• Разделяйте маркетинговый, вспомогательный и OTP-контент по категориям шаблонов.
• Перед увеличением объёма поставок отслеживайте случаи неудачных доставок и жалобы.

Что внедрить в вашу услугу

Полезная интеграция обычно включает в себя следующие компоненты:

Примеры кода

cURL - отправить текст

curl -X POST "https://api.chatarchitect.com/whatsappmessage" \ -u "<APP_ID> :<APP_SECRET> " \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "destination": "<recipient_phone> ", "payload": { "type": "text", "message": "Привет, Джон, как дела?" } }'

Node.js - отправка текста с помощью функции fetch

const APP_ID = process.env.APP_ID; const APP_SECRET = process.env.APP_SECRET; const auth = Buffer.from(`${APP_ID}:${APP_SECRET}`).toString('base64'); async function sendText(destination, text) { const response = await fetch('https://api.chatarchitect.com/whatsappmessage', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${auth}` }, body: JSON.stringify({ channel: 'whatsapp', destination, payload: { type: 'text', message: text } }) }); if (!response.ok) { throw new Error(`Ошибка API ChatArchitect: ${response.status}`); } return response.json(); } sendText('<recipient_phone> ', 'Привет, Джон, как дела?') .then(console.log) .catch(console.error);

Python - отправка текста с помощью запросов

import os import requests APP_ID = os.environ["APP_ID"] APP_SECRET = os.environ["APP_SECRET"] response = requests.post( "https://api.chatarchitect.com/whatsappmessage", auth=(APP_ID, APP_SECRET), headers={"Content-Type": "application/json"}, json={ "channel": "whatsapp", "destination": "<recipient_phone> ", "payload": { "type": "text", "message": "Привет, Джон, как дела?", }, }, timeout=30, ) response.raise_for_status() print(response.json())

Контрольный список тестов

Перед демонстрацией интеграции клиентам воспользуйтесь этим контрольным списком:

• Зарегистрируйте HTTPS-вебхук с помощью /webhook.
• Отправьте обычное текстовое сообщение с помощью /whatsappmessage.
• Убедитесь, что синхронный ответ содержит статус: отправлено.
• Получите заключительный -хук события сообщения с пометками "неудачно, "отправлено", "доставлено"или "прочитано".
• Получите шаблоны с помощью команды /getHSM.
• Отправьте одно утвержденное шаблонное сообщение с реальным значением переменной.
• Функция «Подтвердить неудачную отправку шаблона» отображает причину сбоя веб-перехватчика в вашем сервисе.
• Отправьте входящее сообщение WhatsApp с телефона клиента и подтвердите, что ваш веб-хук получает сообщение root типа: message.

параметры обработки сообщений клиента

Вы можете начать с минимального варианта, а интерфейс для диалогов добавить позже.

Пример описания интеграции с партнерами

При презентации этой функции клиентам используйте краткое описание, подобное этому:

ChatArchitect.com WhatsApp для<Your Service> Отправляйте и получайте сообщения WhatsApp напрямую из<Your Service> Начинайте диалоги с помощью утвержденных шаблонов WhatsApp, получайте ответы от клиентов и автоматически отслеживайте статус доставки с помощью веб-хуков.

Рекомендуемые пункты описания функций:

• Входящие и исходящие сообщения WhatsApp.
• Сообщения, инициированные бизнесом, с использованием утвержденных шаблонов.
• Отслеживание статуса доставки: отправлено, доставлено, прочитано и не доставлено.
• Предварительный просмотр шаблона и сопоставление переменных.
• Дополнительная функция массовой рассылки сообщений с использованием фильтров вашей аудитории.

Рекомендуемый расход

Участник sequenceDiagram Service как Ваш участник сервиса CA как Участник API ChatArchitect WA как Пользователь WhatsApp Service->>CA: POST /webhook CA-->>Service: Webhook saved Service->>CA: POST /getHSM CA-->>Service: Approved templates Service->>CA: POST /whatsappmessage CA-->>Service: status=submitted, messageId CA->>Service: message-event sent/delivered/read/failed WA->>CA: Customer reply CA->>Service: inbound message webhook