연락처

/v1/contacts

contacts 노드를 사용하여 메시지를 보내기 전에 검증하고 ID 해시로 사용자 ID를 확인하는 방법으로 데이터베이스 내의 WhatsApp 사용자를 관리할 수 있습니다.

contacts 노드로 다음과 같은 기능을 수행할 수 있습니다.

• 데이터베이스의 전화번호가 유효한 WhatsApp 계정에 속하는지 확인합니다. status가 valid인지 확인한 다음 사용자에게 메시지를 전송할 수 있습니다.
• 전화번호의 WhatsApp ID를 가져옵니다. WhatsApp ID는 메시지와 사용자 알림을 보내는 데 필요합니다.

시작하기 전에

고객에게 WhatsApp에서 비즈니스와의 의사소통에 동의하는 옵트인 옵션을 표시해야 합니다. 이 옵트인 플로는 비즈니스에서 관리합니다. 고객이 옵트인하면 contacts 노드를 사용해 등록된 번호를 인증합니다. 자세한 내용은 WhatsApp에서 옵트인을 얻는 방법 이해하기를 참조하세요.

제한 사항

• 이 엔드포인트를 사용하여 비즈니스 데이터베이스 내의 전화번호가 유효한 WhatsApp 계정에 속하는지 확인합니다.
• 호출 횟수는 전화번호가 전송하는 메시지 수를 초과할 수 없습니다.

규정 시행

비즈니스가 이 엔드포인트를 오용할 경우 다음과 같은 조치를 취합니다.

• 오용이 의심될 경우 비즈니스 관리자에 나와 있는 모든 관리자의 이메일로 최초 경고를 발송합니다.
• 비즈니스는 경고를 받은 후 7일 안에 행동을 조정해야 합니다.
• 7일이 지난 후에도 호출이 조정되지 않으면 전화번호가 영구적으로 비활성화됩니다.

권장 사항

메시지를 보내기 전에 연락처를 확인하는 것이 좋지만 수신되는 고객 메시지에 응답할 때는 연락처를 확인할 필요 없이 제공된 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와 WhatsApp ID(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"
  }
}

status를 valid로 반환한 전화번호의 WhatsApp ID를 저장합니다. 유효한 사용자는 WhatsApp 계정이 있는 사용자입니다. WhatsApp ID를 사용하여 메시지와 알림을 보냅니다.

이 단계를 정기적으로 반복해 유효한 사용자 리스트를 관리합니다. 결과는 WhatsApp Business 온프레미스 API 클라이언트의 데이터베이스에서 7일 동안 캐시됩니다.

매개변수

/v1/contacts에 대한 POST 호출에 지원되는 매개변수는 다음과 같습니다.

에지

이 노드와 연결되는 에지는 다음과 같습니다.

차단

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시간 이내에 메시지를 전송한 적이 있어야 합니다.

예

다른 WhatsApp 계정을 차단하는 이유와 함께 /v1/contacts/{phone_number}/block으로 API 호출을 보냅니다.

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": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

매개변수

/v1/contacts/{phone_number}/block에 대한 POST 호출에 지원되는 매개변수는 다음과 같습니다.

연락처 차단 해제

연락처의 차단을 해제하려면 이 호출을 보내세요.

예

/v1/contacts/{phone_number}/unblock으로 API 호출을 보냅니다.

POST /v1/contacts/+16315551000/unblock

성공적인 응답에는 HTTP 상태 200이 표시되고 '오류' 개체가 없습니다.

실패한 응답은 다음과 같습니다.

{   
    "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"
        }
    ]
}

매개변수

/v1/contacts/{phone_number}/unblock에 대한 POST 호출에 지원되는 매개변수는 다음과 같습니다.

차단 리스트

차단된 연락처의 리스트를 얻는 방법은 다음과 같습니다.

예

차단된 연락처의 페이지 매김된 리스트를 받으려면 /v1/contacts/blocklist로 API 호출을 보냅니다.

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

페이지 매김 정보와 함께 차단 리스트 페이지가 포함된 응답을 받게 됩니다.

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

매개변수

/v1/contacts/blocklist에 대한 GET 호출에 지원되는 매개변수는 다음과 같습니다.

신고

신고는 악의적 행위자에 대한 예방적 솔루션을 빌드하는 데 중요한 신호를 제공합니다. 연락처를 신고하기 전에 해당 연락처에서 최근 24시간 이내에 메시지를 전송한 적이 있어야 합니다.

예

다른 WhatsApp 계정을 차단하는 경우, 이유를 포함하여 /v1/contacts/{phone_number}/report로 API 호출을 보냅니다.

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": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

매개변수

/v1/contacts/{phone_number}/report에 대한 POST 호출에 지원되는 매개변수는 다음과 같습니다.