배포WhatsApp

발신 메시지 및 템플릿

에이전트에서 WhatsApp 대화와 통화를 시작하세요

개요

에이전트는 활성 대화 내에서만 자유 형식의 WhatsApp 메시지를 보낼 수 있습니다. 알림, 재참여 유도, 예약된 통화 등을 위해 먼저 사용자에게 연락하려면 Meta에서 승인한 메시지 템플릿을 보내야 합니다. 이 페이지에서는 템플릿 생성, 발신 메시지 및 통화 전송, 대규모 운영 방법을 다룹니다.

WhatsApp Manager에서 템플릿 만들기

템플릿은 ElevenLabs가 아닌 WhatsApp Manager에서 생성하고 승인받습니다.

템플릿을 만들 때:

  • 카테고리를 선택합니다. 거래성 메시지에는 Utility, 홍보성 메시지에는 Marketing, 인증 코드에는 Authentication을 선택합니다. Meta는 카테고리별로 요금과 전송률 제한을 다르게 적용합니다. 자세한 내용은 WhatsApp 요금을 참조하세요.
  • 파라미터 형식을 선택합니다. 위치 기반({{1}}, {{2}}) 또는 이름 기반({{customer_name}})을 사용할 수 있습니다. 이름 기반 파라미터는 전송하는 각 값에 parameter_name이 필요합니다.
  • 승인을 위해 제출합니다. 승인에는 보통 몇 분에서 몇 시간이 걸립니다. 대기 중이거나 거부된 템플릿은 보낼 수 없습니다. API는 요청을 수락하지만 Meta는 메시지를 전달하지 않습니다.

Meta는 일정 기간 동안 한 사용자가 받을 수 있는 마케팅 템플릿의 수를 제한합니다. 마케팅 템플릿이 별다른 안내 없이 전달되지 않는다면 이 제한이 흔한 원인입니다(Meta 오류 131049).

발신 메시지 보내기

템플릿 메시지를 보내면 새 대화가 시작됩니다. 사용자가 답장할 때까지 에이전트는 응답하지 않습니다. 템플릿 자체가 첫 번째 메시지이며, 사용자가 응답할 때까지 대화 타이머는 시작되지 않습니다.

WhatsApp 페이지로 이동해 계정을 선택하고 Outbound -> Message 버튼을 클릭합니다. 에이전트를 선택하고 WhatsApp 사용자 ID를 입력한 다음 메시지 템플릿과 파라미터를 선택합니다.

WhatsApp 발신 메시지 대화상자

전체 요청 스키마는 API 레퍼런스를 참조하세요.

AI 어시스턴트가 이 예시를 템플릿에 맞게 조정할 수 있습니다. ElevenLabs 문서의 llms.txt(또는 더 자세한 llms-full.txt)를 제공하고 WhatsApp Manager의 템플릿 정의를 붙여 넣은 뒤 요청을 생성해 달라고 하세요. 템플릿에 맞는 올바른 template_params가 포함된 cURL 명령어나 SDK 호출을 생성합니다.

템플릿 파라미터

template_params는 파라미터가 있는 각 템플릿 구성 요소당 하나씩 포함하는 component 객체 목록입니다.

  • 본문 자리표시자에는 {"type": "body", "parameters": [...]}
  • 파라미터가 있는 헤더(텍스트, 이미지, 문서 또는 위치)에는 {"type": "header", "parameters": [...]}
  • 버튼 파라미터에는 {"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}

parameters의 각 항목은 {"type": "text", "text": "Daniele"}와 같은 값 객체입니다. 이름 기반 파라미터가 있는 템플릿의 경우 각 값에 parameter_name을 포함하세요. 예를 들어 template_params에 {"type": "text", ...}를 직접 전달하는 것처럼 구성 요소 래퍼를 생략하면 거부됩니다.

수신자 번호 형식

whatsapp_user_id에는 국가 코드와 번호를 이어 붙인 숫자만 포함해야 하며, +, 공백 또는 대시는 사용할 수 없습니다. 예: +1 (415) 555-2671이 아닌 14155552671.

일부 국가에서는 WhatsApp이 개인에게 사용하는 ID가 해당 사용자의 다이얼 번호와 다릅니다. 예를 들어 멕시코 번호에는 국가 코드 뒤에 추가 1이 붙고(521...), 브라질 번호에는 아홉 번째 숫자가 포함되거나 생략될 수 있습니다. 사용자가 이전에 메시지를 보낸 적이 있다면 대화 기록에서 복사할 수 있는 이전 대화의 whatsapp_user_id를 우선 사용하세요.

동적 변수, 브랜치 및 환경

conversation_initiation_client_data 필드로 대화의 동적 변수를 설정하고 특정 에이전트 브랜치 및 환경에 고정할 수 있습니다.

{
  "dynamic_variables": { "customer_name": "Daniele" },
  "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0",
  "environment": "staging"
}

이 설정은 대화 내내 유지됩니다. 사용자가 답장하면 에이전트는 요청된 브랜치와 환경에서 재개됩니다. 브랜치와 환경이 먼저 검증되므로, 둘 중 하나라도 존재하지 않으면 요청은 오류와 함께 실패하며 메시지는 전송되지 않습니다.

이 요청 필드를 통해 발신 대화에 동적 변수가 전달됩니다. 반면 수신 대화는 대화 시작 웹훅을 통해 이를 받습니다. 자세한 내용은 초기화 컨텍스트를 참조하세요.

템플릿 파라미터는 템플릿 텍스트만 채우며 에이전트에 노출되지 않습니다. 에이전트가 템플릿의 값(예: 고객 이름)을 알아야 한다면 해당 값을 dynamic_variables로 다시 전달하세요.

전송 후

요청이 성공하면 conversation_id가 반환되며, 렌더링된 템플릿이 첫 번째 메시지로 표시된 대화가 기록에 나타납니다. 사용자가 답장할 때까지 에이전트는 실행되지 않습니다. 템플릿을 보내도 최대 지속 시간 타이머와 비활성 타이머는 시작되지 않으며, 둘 다 대화가 재개된 후 시작됩니다. 200 응답은 ElevenLabs가 요청을 수락했다는 의미이며, 이후에도 Meta가 전달을 거부할 수 있습니다. 메시지가 도착하지 않으면 문제 해결을 참조하세요.

발신 통화 예약하기

발신 WhatsApp 통화에는 사용자의 권한이 필요합니다. 사용자 통화 권한을 참조하세요. WhatsApp Manager에서 통화 권한 요청 구성 요소가 포함된 메시지 템플릿을 만드세요. 통화를 예약하면 ElevenLabs가 권한 상태를 확인합니다.

  • 권한이 이미 부여된 경우: 즉시 통화가 연결됩니다.
  • 아직 권한을 요청하지 않은 경우: 권한 요청 템플릿이 전송되며, 사용자가 승인하는 즉시 통화가 연결됩니다.
  • 권한이 거부된 경우: 대화는 User declined the call permission request. 사유로 실패 처리됩니다.

WhatsApp 페이지로 이동해 계정을 선택하고 Outbound -> Call 버튼을 클릭합니다. 에이전트를 선택하고 WhatsApp 사용자 ID를 입력한 다음 통화 권한 요청 템플릿을 선택합니다.

WhatsApp 발신 통화 대화상자

전체 요청 스키마는 API 레퍼런스를 참조하세요. 발신 메시지와 마찬가지로 conversation_initiation_client_data는 동적 변수를 설정하고 대화를 브랜치와 환경에 고정하며, 존재하지 않는 브랜치나 환경은 통화 예약 전에 거부됩니다.

Meta는 발신 통화와 고객 서비스 창 외부에서 전송된 통화 권한 요청에 대해 요금을 부과합니다. 통화를 예약하기 전에 WhatsApp Manager에 결제 수단을 추가하세요.

캠페인 및 일괄 처리

여러 사용자에게 전화를 걸려면 whatsapp_params와 함께 일괄 통화를 사용하세요. 전화번호 ID와 통화 권한 요청 템플릿은 한 번 제공하고, 수신자별로 whatsapp_user_id를 제공합니다.

발신 메시지용 네이티브 일괄 엔드포인트는 아직 없습니다. 템플릿 캠페인의 경우 수신자마다 한 번씩 발신 메시지 엔드포인트를 호출하고, 번호에 적용되는 Meta의 메시지 제한을 준수하세요. 메시지 제한을 참조하세요.