Webhooks는 사용자가 정의한 HTTP 콜백으로, 특정 이벤트가 발생하면 트리거됩니다. 트리거 이벤트가 발생할 때마다 WhatsApp Business API 클라이언트는 이벤트를 확인하고, 데이터를 수집하고, 즉시앱 설정에 지정된 Webhook URL로 알림(HTTP 요청)을 전송하여 전송된 메시지의 상태를 업데이트하거나 언제 메시지를 수신했는지 알립니다.
webhooks: Webhook에 URL을 제공합니다. Webhooks를 사용하고 있는 경우필수입니다. Webhook URL이 설정되지 않은 경우 콜백이 실패합니다. Webhooks를 확인하고 테스트할 수 있는 간단한 방법은샘플 테스트 앱을 참조하세요.
sent_status: 서버가 메시지를 수신했을 때 알림을 받고 싶은 경우 지정하세요. 기본적으로 이 알림은 꺼짐으로 설정되어 있습니다.
callback_persist: Webhook가 성공적으로 인식할 때까지 콜백을 디스크에 저장할지 여부를 선택합니다. 실패한 알림(HTTPS 200응답이 아닌 경우)은 제한 없이 다시 시도할 수 있습니다. 이 설정을 사용하여 재시도를 구성하세요.
샘플 테스트 앱
Webhook에 메시지를 전송하는 방법은 교차 플랫폼 런타임 환경(node.js)을 만들고 서버 측 JavaScript 앱(server.js)을 실행하여 JSON 형식을 파싱하기 위한 엔드포인트 핸들러 코드를 구현하는 것이 있습니다. 핸들러는 Webhook으로 메시지 알림의 송수신을 라우팅합니다.
원하는 도구를 사용하여 Webhook의 행동을 확인할 수 있습니다.Glitch에서 만든 샘플node.js앱을 제공하였으므로 이를 복제해 사용할 수 있습니다. 프로젝트를 "리믹스"하면 새 프로젝트가 생기는데, 이 프로젝트는Express를 사용하여 WhatsApp Business API 클라이언트에서 전송 가능한 Webhook 엔드포인트를 노출합니다. 아래의 단계에 따라 어떻게 작동하는지 확인하세요!
Glitch에서 리믹스하기버튼을 클릭합니다(
).
프로젝트가 생성되면 URL은https://<project-name>.glitch.me형식이 됩니다(또는 상단의앱 표시를 클릭하기만 하면 URL로 이동합니다).
왼쪽 내비게이션 창에서server.js를 선택하고 Webhook 엔드포인트 구현을 확인합니다.
왼쪽 내비게이션 창에서상태버튼을 클릭합니다. 앱이 특정 포트에서 수신하고 있다는 것이 보일 것입니다.
앱 설정을 사용하여 새로 만든 프로젝트(위의 2단계)를 가리키도록 Webhook URL을 설정합니다. 프로젝트 URL에/webhook을 노출되는 엔드포인트로 추가합니다(예:https://<project-name.glitch.me/webhook).
다른 사람 또는 자신에게 테스트 메시지를 보내서 알림을 확인합니다. 다음의 로그 예시는 본문에 "Hi"라고 적혀 있는 문자 메시지를 수신한 다음 전송된 메시지의 상태가 전송됨, 전달됨, 읽음으로 업데이트되는 과정을 보여줍니다.Incoming webhook:{"messages":[{"from":"1234567890","id":"ABGGhSkIc2B_Ago-sDy5BNm-1gI5","text":{"body":"Hi"},"timestamp":"1529381066","type":"text"}]}Incoming webhook:{"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"sent","timestamp":"1529381072"}]}Incoming webhook:{"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"delivered","timestamp":"1529381072"}]}Incoming webhook:{"statuses":[{"id":"gBGGhSkIc2B_AgkXDygfSDwgG5s","recipient_id":"1234567890","status":"read","timestamp":"1529381076"}]}
Webhook의 일반 형식
Webhook에는 현재 무엇이 전송되고 있는지 나타내는 최상위 배열 필드가 포함됩니다. 배열 멤버는 Webhook와 관련된 상세한 필드를 포함한 JSON 개체가 됩니다.
이름개체 내용
messages
인바운드 메시지 알림
statuses
메시지 상태 업데이트
errors
중대한 대역 외 오류
가능하면 이름은 모든 함수에서 상수로 유지하세요. 예를 들어 모든 타임스탬프는timestamp라고 합니다.
알림 Webhook의 형식
알림 Webhook의 모든 가능한 필드는 아래와 같습니다.샘플 테스트 앱에서 논의했듯이 메시지를 주고받으면서 트리거되는 엔드포인트 핸들러를 만들 것입니다. 앞서 상술한 바와 같이 여기에서는 두 개의 메인 Webhook(inbound notifications와message statuses)에 대한 자세한 내용의 문서를 제공합니다. 오류는 아래를 참조하세요.
POST /{"contacts":[{"profile":{"name":"sender-profile-name"},"wa_id":"wa-id-of-contact"}],"messages":["context":{"from":"sender-wa-id-of-context-message","group_id":"group-id-of-context-message","id":"message-id-of-context-message","mentions":["wa-id1","wa-id2"],"forwarded":true|false,"frequently_forwarded":true|false},"from":"sender-wa-id","group_id":"group-id","id":"message-id","timestamp":"message-timestamp","type":"audio | document | image | location | system | text | video | voice",#If there are any errors the errors field (array) will be present.#The errors field can be returned as part of any callback event."errors":[{...}],"audio":{"file":"absolute-filepath-on-coreapp","id":"media-id","link":"link-to-audio-file","mime_type":"media-mime-type","sha256":"checksum"}"document":{"file":"absolute-filepath-on-coreapp","id":"media-id","link":"link-to-document-file","mime_type":"media-mime-type","sha256":"checksum","caption":"document-caption"}"image":{"file":"absolute-filepath-on-coreapp","id":"media-id","link":"link-to-image-file","mime_type":"media-mime-type","sha256":"checksum","caption":"image-caption"}"location":{"address":"1 Hacker Way, Menlo Park, CA, 94025","latitude":latitude,"longitude":longitude,"name":"location-name"}"system":{"body":"system-message-content"}"text":{"body":"text-message-content"}"video":{"file":"absolute-filepath-on-coreapp","id":"media-id","link":"link-to-video-file","mime_type":"media-mime-type","sha256":"checksum"}"voice":{"file":"absolute-filepath-on-coreapp","id":"media-id","link":"link-to-audio-file","mime_type":"media-mime-type","sha256":"checksum"}]}
알림 오류
앱이 정상 작동하는 동안 대역 외 오류가 발생할 경우errors배열이 오류에 대한 설명을 제공합니다. 이런 유형의 오류는 일시적인 네트워크 연결 오류, 잘못된 자격 증명, 관리 컨트롤러의 사용 불가 상태 등으로 인해 발생합니다. 모든 수신 오류에 대한 자세한 내용은오류 및 상태 메시지를 참조하세요.
예시
POST /{"errors":[{"code":<error-code>,"title":"<error-title>","details":"<error-description>","href":"location for error detail"},{...}]}errors개체
댓글