Consent and the 24-hour window
WhatsApp has strict rules. The API enforces them on the server. You cannot send around them, even with a key that has every permission.
#Opt-in
Each contact has a field optin_whatsapp:
| Value | Meaning |
|---|---|
none | No opt-in asked yet. |
pending | An opt-in message was sent, no answer yet. |
confirmed | The contact said yes. |
opted_out | The contact unsubscribed. |
Which kind of message a contact may receive depends on this value:
| Kind of message | none, pending | confirmed | opted_out |
|---|---|---|---|
| Free text, inside the 24-hour window (send message call) | yes | yes | yes, only as an answer inside the open window (the person just wrote to you) |
| Free text, window closed | window_closed | window_closed | contact_opted_out |
| Approved template (send template message call) | contact_not_confirmed | yes | contact_opted_out |
| Newsletter | not sent, counted as not_confirmed | yes | not sent, counted as opted_out |
| Opt-in request (opt-in confirmation call) | only none without a running request; pending is skipped | skipped, not needed | never |
| Test send | yes, the number does not need to be a contact | yes | contact_opted_out |
A number on the suppression list gets nothing at all and the answer is number_suppressed.
- The API never sets a contact to
confirmed. Only the contact can confirm, by answering the opt-in message. You can ask for the opt-in with the opt-in confirmation call. - A newsletter only goes to contacts with
confirmed. - Only a contact with
confirmedcan be unsubscribed through the API. For any other contact the unsubscribe call answerscontact_not_confirmed, because such a contact gets no marketing anyway. - A call that tries to send to a contact who may not receive it fails with
contact_not_confirmed,contact_opted_outornumber_suppressed.
#The 24-hour window
After a contact writes to you, a window of 24 hours opens. Inside it you may send free text. After it closes, free text is not possible. The answer is window_closed. Send an approved template instead.
#Approved templates only
Outside the inbox, messages go out only as templates that WhatsApp has approved. Variables in a template are filled with values you send; missing values give template_variables_missing. A template that is not approved gives template_not_approved.
This also holds for test sends: a test goes to the number you name, but only with an approved template, and never to a contact who unsubscribed.
#Unsubscribing
Use the unsubscribe call to mark a contact as opted_out. This cannot be undone through the API.