API документов WhatsApp: выстройте процесс вокруг PDF

Отправить PDF легко. Выстроить надежный бизнес-процесс вокруг него — гораздо сложнее.

Актуальная документация Meta по сообщениям с документами объясняет, как WhatsApp Business Platform отправляет документ в виде медиаобъекта. В июле 2026 года Meta также объявила, что пользователи могут открывать PDF прямо в WhatsApp, а в веб-версии и приложении для компьютера — делать простые выделения и пометки (июльское обновление WhatsApp от Meta). Это полезные улучшения, но они не определяют, какая версия считается основной, кто отвечает за возвращенный файл и что означает завершение процесса.

В этом и состоит суть надежного процесса с WhatsApp document API: сообщение переносит файл, а операционная модель ведет дело к подтвержденному результату. Ни доставка, ни прочтение сообщения сами по себе не доказывают, что получатель изучил документ.

1. Отделите передачу документа от завершения дела

Платформенный уровень отвечает на узкий вопрос: можно ли отправить этому получателю сообщение с документом в правильном контексте беседы? В документации Meta приведен запрос для такого сообщения, а также поддерживаются подпись и имя файла (сообщения с документами у Meta). Бизнес-уровень должен ответить на остальные вопросы:

• Тот ли это файл для данного клиента и цели?
• Это текущая утвержденная версия?
• Допустимо ли отправлять его этому адресату по выбранному каналу?
• Кто отвечает за вопросы, исправления и возвращенный экземпляр?
• Какое событие закрывает дело?
• Когда должны истечь срок файла и пути доступа к нему?

Если считать sent равным complete, все шесть вопросов сводятся к одному событию доставки. Более надежная схема использует две связанные сущности: запись сообщения для состояния канала и дело документа для бизнес-результата. Сообщение может не отправиться, быть доставлено или прочитано. Дело может ждать проверки, требовать исправления, получить новую редакцию, пройти валидацию или закрыться.

Такое разделение предотвращает и распространенную ошибку измерения. Отметка о прочтении относится к сообщению WhatsApp, а не доказывает, что PDF был открыт, понят, аннотирован, подписан или принят. Фиксируйте только тот результат, который система действительно наблюдает.

2. Дайте каждому делу устойчивый идентификатор

До вызова API создайте постоянную запись дела. Как минимум в ней нужны:

• document_case_id — Устойчивый идентификатор бизнес-процесса
• contact_id — Идентификатор получателя в управляемой клиентской системе
• document_type — Счет, предложение, продление, заявление или другой контролируемый тип
• document_version — Неизменяемая версия, отправляемая в этой попытке
• purpose — Причина, по которой адресат должен получить файл
• owner_id — Сотрудник или очередь, отвечающие за следующее действие
• state — Текущее бизнес-состояние независимо от доставки сообщения
• source_hash — Контроль целостности точного файла, если это предусмотрено политикой безопасности
• retention_class — Утвержденное правило хранения и удаления
• message_id — Идентификатор сообщения, возвращенный после отправки

Не используйте имя файла как идентификатор дела. renewal.pdf может относиться к разным клиентам и версиям. Имя файла — представление; document_case_id и document_version — контроль.

Практичная модель состояний: draft, approved_to_send, sent, delivered, waiting_for_customer, revision_received, needs_correction, verified, completed и expired. Состояний может быть меньше, но каждое должно обозначать решение, меняющее ответственного или допустимые действия.

3. Проведите предпроверку из семи шлюзов

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

1. Цель: файл и сопроводительное сообщение соответствуют документированному запросу клиента или разрешенной деловой цели.
2. Получатель: контакт и номер однозначно принадлежат нужному человеку; неоднозначность отправляется на проверку.
3. Версия: дело ссылается на утвержденный неизменяемый файл, а не на изменяемый путь «latest».
4. Доступ: медиассылка и срок хранения отвечают политике безопасности; публичный доступ не остается дольше необходимого.
5. Представление: имя и подпись понятны и не содержат внутренних заметок или чувствительных идентификаторов.
6. Правило беседы: используется верный путь — свободное сообщение или утвержденный шаблон — для текущего сервисного окна WhatsApp.
7. Ответственность: конкретный человек или очередь готовы обработать вопрос, замену или возвращенный документ.

В актуальном API DripTell есть POST /api/v1/send/media: он отправляет изображение, видео, аудио, документ или стикер по общедоступному HTTPS-адресу, поддерживает необязательную подпись и имя документа (документация DripTell для разработчиков). Эндпоинт полезен лишь после прохождения семи шлюзов. Технически корректный запрос еще не означает корректного бизнес-решения.

Сохраняйте результат предпроверки с кодами причин: wrong_recipient, unapproved_version, expired_link, window_closed или no_owner. Тогда отказ от отправки будет объяснимым и пригодным для безопасного повтора.

4. Сделайте исходящую отправку идемпотентной

В документообороте легко получить дубликаты. После сетевого тайм-аута вызывающая система может не знать, принят ли файл. Оператор нажмет повтор, а планировщик может запуститься дважды. Если каждая попытка порождает новое сообщение, клиент получит несколько экземпляров и не поймет, какой актуален.

Создайте ключ идемпотентности из дела, версии, получателя и действия, например case_482:v3:send_for_review. Перед отправкой проверьте, нет ли у этого действия уже успешного идентификатора сообщения. Если есть, верните существующий результат. Если нет, отправьте один раз и сохраните идентификатор рядом с точной версией документа.

Состояние доставки обрабатывайте отдельно. Модель webhook Meta передает обновления статусов и объекты входящих сообщений (компоненты webhook Meta Cloud API). Эти события обновляют транспортное состояние, но бизнес-состояние должно оставаться осторожным:

• sent означает, что платформа приняла попытку;
• delivered — что по событию канала сообщение дошло до устройства адресата;
• read — что сообщение отмечено прочитанным, а не что документ проверен;
• failed — что нужен обоснованный повтор или другой разрешенный маршрут.

Не создавайте новую версию документа только из-за сбоя доставки. Версия меняется при изменении содержания, а не при повторе канала.

5. Считайте возвращенный PDF новым доказательством

Входящий путь требует не меньше внимания. В актуальном API DripTell есть POST /api/send/media/fetch для получения медиафайла от контакта WhatsApp. Файл должен принадлежать той же рабочей области, что и bearer-ключ, а запрос может ссылаться на ID сообщения или медиа (документация DripTell для разработчиков).

Когда документ приходит:

1. привязывайте ID входящего сообщения к открытому делу только при совпадении контакта и ожидаемого состояния;
2. получайте файл по управляемому серверному пути, а не из браузерного кода и не с секретом в публичном клиенте;
3. проверяйте тип, размер и безопасность средствами, утвержденными в вашей организации;
4. сохраняйте его как новый неизменяемый объект доказательства, не перезаписывая отправленный оригинал;
5. фиксируйте исполнителя или систему проверки и результат;
6. назначайте дело правильному проверяющему и задавайте срок;
7. подтверждайте получение, но не обещайте принятие до проверки.

Если открытого дела нет, направьте файл в ограниченную очередь исключений. Не угадывайте по похожему имени. Клиент мог вернуть не то вложение, ответить с другого номера или прислать посторонний документ.

6. Сохраняйте редакции, а не переписывайте историю

Июльское обновление Meta упрощает работу с PDF в веб-версии и приложении для компьютера: в чате доступны легкие выделения и пометки. Это снижает трение, однако аннотированный экземпляр остается новым объектом и не должен незаметно заменять основной оригинал.

Используйте простую цепочку:

source_v3 → sent_copy_v3 → customer_annotation_1 → approved_final_v3

Каждая стрелка — документированная связь, а не перезапись. Сохраняйте исходную версию, идентификатор полученного файла, время, результат проверки и решение. Если клиент лишь выделил вопрос, делу может требоваться пояснение, а не одобрение. Если компания меняет содержание, создайте source_v4 и явно отметьте v3 как замененную.

Не превращайте WhatsApp в единственное хранилище. Беседа — это поверхность взаимодействия; источником истины для доступа, хранения и финального состояния должна оставаться управляемая документная система или запись дела.

7. Пример: пакет продления аренды

Представим управляющую компанию, которая отправляет пакет продления. Дело создается с идентификатором арендатора, объектом, утвержденной версией PDF, целью, ответственным и сроком ответа. Система проверяет адресата, допустимый маршрут беседы, контролируемую медиассылку, понятное имя файла и наличие владельца.

После отправки транспортные события обновляют сообщение. Дело переходит в waiting_for_customer после доставки, но не в completed при прочтении. Арендатор возвращает PDF с пометкой и вопросом по пункту. Файл становится customer_annotation_1, направляется в очередь команды, а дело — в needs_correction или needs_answer.

Команда отвечает и, если содержание изменилось, выпускает новую утвержденную версию. Дело закрывается, когда необходимое бизнес-доказательство получено и проверено по внутреннему процессу. Это операционный пример, а не юридическая консультация и не утверждение, что пометка равна подписи.

Главное достоинство — объяснимость. В любой момент можно ответить: какой файл, кому и зачем отправили, что вернулось, кто отвечает и какого события не хватает?

8. Измеряйте только доказуемую воронку

Стройте метрики по слоям, а не одним вводящим в заблуждение «коэффициентом конверсии PDF».

Транспортные метрики: принятие отправки, доставка, прочтение, сбой и причина. Они описывают канал.

Метрики процесса: время от доставки до первого ответа, от возврата до назначения, время в исключении, число редакций, доля успешной проверки и время до подтвержденного завершения. Они описывают операцию.

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

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

9. Реализуйте процесс в DripTell

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

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

Начните с одного типа документа и одного события завершения. До автоматизации отправки опишите состояния, семь шлюзов, путь исключения и ответственного. Затем протестируйте обычный возврат, неверную версию, повторную попытку, непривязанный файл и просроченное дело.

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