Support for the standalone WhatsApp API will end on September 30, 2023. New customers must use, and existing customers must migrate to, the WhatsApp channel of the Conversation API. Any migration must be completed prior to September 30, 2023.

Examples

Use cases for the Sinch WhatsApp API

Interactive message templates

Interactive message templates can have three types of buttons:

quick reply button
call button
URL button (Static and Dynamic)

When the user clicks on a button, it triggers an action.

Message template with quick reply buttons

Suppose there exists a message template with the following data.

Template body:

Copy

Copied

Hi {{1}}.

Your order of {{2}} has been prepared for shipping. We can send the ticket to you in three different ways.
1. {{3}}
2. {{4}}
3. {{5}}

Please select your preferred delivery option.

Template quick reply buttons:

Email
Post
WhatsApp

Template preview:

Example of a message using this template:

Copy

Copied

{
  "to": [
    "46732019282"
  ],
  "message": {
    "type": "template",
    "template_name": "deal_offer",
    "language": "en",
    "body_params": [
      "John",
      "a ticket",
      "Email",
      "Post",
      "WhatsApp"
    ],
    "media" : {
      "type": "text"
    },
    "buttons" : [
      {
        "type": "quick_reply",
        "payload": "email"
      },
      {
        "type": "quick_reply",
        "payload": "post"
      },
      {
        "type": "quick_reply",
        "payload": "whatsapp"
      }
    ]
  }
}

Example result on the phone:

The quick reply button payload, which is returned in a callback notification when the recipient presses that button, could be used to easily collect statistics about the most popular delivery choices for instance.

Message template with a static URL button

Suppose there exists a message template with the following data.

Template body:

Copy

Copied

Hello, {{1}}. Your account has been updated.

Template buttons:

URL of type Static

Template preview:

Example of a message using this template:

Note

The buttons element is not required here as the button is of Static URL type.

Copy

Copied

{
    "to": [
        "46732019282"
    ],
    "message": {
        "type": "template",
        "template_name": "test_template_static_url",
        "language": "en",
        "body_params": [
            "Stephanie"
        ]
    }
}

Example result on the phone:

Message template with a dynamic URL button

Suppose there exists a message template with the following data.

Template header:

Copy

Copied

Incident {{1}} solved

Template body:

Copy

Copied

Hello {{1}}

An incident {{2}} that you reported was solved by our team.

Please check your account.

Template buttons:

URL of type Dynamic

Template preview:

Example of a message using this template:

(Here buttons element is required because a button is of Dynamic URL type and a parameter needs to be provided.)

Copy

Copied

{
    "to": [
        "46732019282"
    ],
    "message": {
        "type": "template",
        "template_name": "test_template_dynamic_url",
        "language": "en",
        "header_params": [
            "INR0001234"
        ],
        "media": {
            "type": "text"
        },
        "body_params": [
            "Frederic", "INR0001234"
        ],
        "buttons": [
            {
                "type": "url",
                "parameter": "987654"
            }
        ]
    }
}

Example result on the phone:

Product messages

Product messages include references to one or more products in a Facebook product catalog. The recipient can reply with questions about a product or place an order.

Sending product messages

There are two different types of product messages you can send:

Single product message
Product list message

Receiving responses to product messages

The reciepent can respond to product messages in two ways:

Ask for information
Place an order

Single product message

A single product message includes a reference to a single product in a Facebook product catalog.

Copy

Copied

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "product",
      "body": {
        "text": "Blue shoes"
      },
      "footer": {
        "text": "Also available in yellow"
      },
      "action": {
        "catalog_id": "catalogid",
        "product_retailer_id": "productretailerid",
      }
    }
  }
}

Product list message

A product list message includes references to one or more products in a Facebook product catalog. These product references (max 30) are placed in sections (max 10).

Copy

Copied

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "product_list",
      "header": {
        "type": "text",
        "text": "New products available!"
      },
      "body": {
        "text": "Our new collection is finally here."
      },
      "footer": {
        "text": "Thank you for your interest."
      },
      "action": {
        "catalog_id": "catalogid",
        "sections": [
          {
            "title": "Headwear",
            "product_items": [
              {
                "product_retailer_id": "product1"
              },
              {
                "product_retailer_id": "product2"
              }
            ]
          },
          {
            "title": "Footwear",
            "product_items": [
              {
                "product_retailer_id": "product3"
              }
            ]
          }
        ]
      }
    }
  }
}

Ask for information

The recipient can ask for information about a product. In this case, the message that is sent back will contain a reference to the specific product.

Inbound text message with a product referenceInbound audio message with a product reference

Copy

Copied

{
  "type": "whatsapp",
  "contacts": [
    {
      "profile": {
        "name": "John Smith"
      },
      "wa_id": "0732001122"
    }
  ],
  "notifications": [
    {
      "from": "0732001122",
      "to": "sinchbot",
      "replying_to": {
        "from": "447537817391",
        "message_id": "01E7Q9AVTRB5A30JD7D9ZN0HTE"
      },
      "message_id": "01DPNXZ0WCF9XD19MH84XD0P62",
      "message": {
        "type": "text",
        "body": "Hi, do you have this product in red?",
        "referred_product": {
          "catalog_id": "catalogid",
          "product_retailer_id": "productid",
        }
      },
      "timestamp": "2020-05-02T19:48:42Z"
    }
  ]
}

Copy

Copied

{
  "type": "whatsapp",
  "notifications": [
    {
      "from": "0732001122",
      "to": "sinchbot",
      "message_id": "01DPNXZ0WCF9XD19MH84XD0P62",
      "message": {
        "type": "audio",
        "filename": "Question",
        "caption": "Caption",
        "url": "http://www.example.com/audio.ogg",
        "mime_type": "audio/ogg",
        "referred_product": {
          "catalog_id": "catalogid",
          "product_retailer_id": "productretailerid",
        }
      },
      "timestamp": "2020-05-02T15:43:52Z"
    }
  ]
}

Place an order

The recipient can place an order for one or more products. The order message will contain information about which products are ordered.

Copy

Copied

{
  "type" : "whatsapp",
  "notifications" : [
    {
      "from" : "0732001122",
      "message_id" : "01DPNXZ0WCF9XD19MH84XD0P62",
      "message" : {
        "type" : "order",
        "text" : "Here's my order",
        "catalog_id" : "catalogid",
        "product_items" : [
          {
            "product_retailer_id" : "product1",
            "quantity" : 10,
            "item_price" : 10.2,
            "currency" : "USD"
          },
          {
            "product_retailer_id" : "product2",
            "quantity" : 2,
            "item_price" : 4,
            "currency" : "SEK"
          }
        ]
      },
      "timestamp" : "2021-06-07T13:38:36Z",
      "to" : "sinchbot"
    }
  ]
}