Opt-in & Opt-out

Registering Opt-in & Opt-out requests

Introduction to Opt-in & Opt-out

By using the Opt-in & Opt-out service, it's possible to register an opt-in or an opt-out event for a contact with the underlying channel. In order to execute the request, either the contactId of the contact or its channel recipient identities are required.

Currently Opt-In & Opt-Out registration is supported for any channels that support Opt-In & Opt-Out, including WhatsApp. To read more about relevant WhatsApp policies, go to WhatsApp Opt-in and Opt-out.

Requests are executed asynchronously, therefore the endpoint immediately returns the registered request. The result of the Opt-in or Opt-out request is posted to the webhook which has an OPTIN or OPTOUT trigger respectively. To read more about setting up webhooks go to Webhooks.

Opt-in

Opt-in Request

Below you can find an example to register an Opt-in event.

Conversation API POST optins:register

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "contact_id": "{{CONTACT_ID}}"
  }
}

Alternatively the contact's channel recipient identities can be used:

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "14707864783"
        }
      ]
    }
  }
}

Opt-in Response

The response for Opt-in is the registered request. The result is returned through the webhook with OPT_IN trigger, see Opt-In Notification.

Opt-in Notification

The result of registering an Opt-in is posted to the webhook which has OPT_IN trigger set.

Below you can find an example for Opt-in Notification.

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "opt_out_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "WHATSAPP",
    "identity": "46712312312",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
  }
}

The Opt-in Notification can have the following fields:

Possible values for status are:

• OPT_IN_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-in.
• OPT_IN_SUCCEEDED : the Opt-in registration succeeded.
• OPT_IN_FAILED : the Opt-in registration failed, see reason in error_details field.

Opt-out

Opt-out Request

Below you can find an example to register an Opt-out event.

Conversation API POST optouts:register

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "opt_out_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "WHATSAPP",
    "identity": "46712312312",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
  }
}

Alternatively the contact's channel recipient identities can be used:

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "14707864783"
        }
      ]
    }
  }
}

Opt-out Response

The response for Opt-out is the registered request. The result is returned through the webhook which has OPT_OUT trigger, see Opt-Out Notification.

Opt-out Notification

The result of registering an Opt-out is posted to the webhook which has OPT_OUT trigger set.

Below you can find an example for Opt-out Notification.

{
  "contact_id": "{{CONTACT_ID}}",
  "channel": "WHATSAPP",
  "identity": "46712312312",
  "status": "OPT_OUT_SUCCEEDED"
}

The Opt-out notification can have the following fields:

Possible values for status are:

• OPT_OUT_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-out.
• OPT_OUT_SUCCEEDED : the Opt-out registration succeeded.
• OPT_OUT_FAILED : the Opt-out registration failed, see reason in error_details