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