Send WhatsApp Messages

Send messages via WhatsApp with Sinch WhatsApp API. Get more information here.

The message endpoint is used as the primary endpoint of the API and this is where all the messages are sent through.

WhatsApp message flow

1. Customer opt-in is essential before sending any messages. The Sinch WhatsApp Business Messaging API does not check whether recipients have opted in before sending messages, so the user must ensure that the recipient has opted in before sending. For more information on the opt-in and opt-out requirements for WhatsApp messages, see the WhatsApp Business Policy .
2. Businesses can only start a conversation with a defined approved WhatsApp template . Templates can be created on the Sinch Customer Dashboard .
3. Once you get a reply from your customer, a customer care session starts. You can then send “session” rich content messages for 24 hours.
4. Every time a customer replies to one of your messages, a new 24-hour cycle starts.
5. If a “session” expires, you’ll need to re-initiate a conversation, starting with a defined message template again.
6. Customers can start a rich content conversation with a business at any time; this opens up a new 24-hour session.

Send a WhatsApp message

Request

POST whatsapp/v1/{bot-id}/messages

JSON object parameters:

Response

201 Created

The response body is a JSON object with the same format as a delivery report callback.

{
  "type": "whatsapp",
  "statuses": [
    {
      "message_id": "01DPNXZ0WCF9XD19MH84XD0P62",
      "recipient": "+46732001122",
      "status": "success",
      "state": "queued"
    }
  ]
}

400 Bad Request

There was an error with your request. The body of the error is a JSON object described in the introduction.

401 Unauthorized

There was an authentication error with your request. Either you're using incorrect credentials or you're attempting to authenticate in a region where your bot doesn't reside. The body of the error is a JSON object described in the introduction.

403 Forbidden

Your request has been received, but access is forbidden. The WhatsApp bot you are using to send messages has been suspended. This can happen for various reasons, including outstanding charges. The body of the error is a JSON object described in the introduction.

500 Internal Server Error

An unexpected error occurred before queueing your message or while your message was being queued. The body of the error is a JSON object described in the introduction.

Message object types

The types of messages that can be sent are one of the following:

• Template Message
• Text Message
• Image Message
• Video Message
• Document Message
• Audio Message
• Location Message
• Contacts Message
• Sticker Message
• Interactive Message

Template message

In order to send a template message, you must use an approved WhatsApp template. WhatsApp templates can be created using the Sinch Customer Dashboard. Your Sinch Account Manager may also help you create templates during onboarding. In either case, the created templates are submitted to Meta for approval. Once Meta approves a template, you'll be able to use it to send template messages.

When creating template messages, note the following:

• Accepted language codes can be found in the introduction .
• You can use media provider feature in template messages.
• As of 29th June, 2021 , the use of the ttl parameter when sending template messages is DEPRECATED. WhatsApp no longer supports the feature.

The table below provides the JSON object parameters:

Examples:

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "test_template",
    "language": "en",
    "body_params": ["param here"],
    "media": {
      "type": "text"
    }
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "demo_rich_text",
    "language": "en",
    "header_params": ["Nick"],
    "body_params": ["Swan Lake"],
    "media": {
      "type": "text"
    }
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "demo_image",
    "language": "en",
    "body_params": ["Swan Lake"],
    "media": {
        "type": "image",
        "url": "https://picsum.photos/200"
    }
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "demo_image",
    "language": "en",
    "body_params": ["John", "Parker"],
    "media": {
        "type": "document",
        "url": "https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf"
    }
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "demo_video",
    "language": "en",
    "body_params": ["John", "Parker"],
    "media": {
        "type": "video",
        "url": "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_480_1_5MG.mp4"
    }
  }
}

Templates with buttons

• Call button

• URL button

• Quick reply button

Find more button examples here.

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "some_template_name",
    "language": "en",
    "body_params": ["some_first_parameter", "some_second_parameter"],
    "media": {
      "type": "image",
      "url": "https://www.example.com/some_image.jpg",
      "provider": "some_provider_name"
    },
    "buttons": [
      {
        "type": "call"
      },
      {
        "type": "url",
        "parameter": "some_url_parameter"
      }
    ]
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "template",
    "template_name": "some_template_name",
    "language": "en",
    "header_params": ["some_parameter"],
    "body_params": ["some_first_parameter", "some_second_parameter"],
    "media": {
      "type": "text"
    },
    "buttons": [
      {
        "type": "quick_reply",
        "payload": "some_quick_reply_payload"
      },
      {
        "type": "quick_reply"
      }
    ]
  }
}

Text message

Available formatting and using emojis for the text message content can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "text",
    "preview_url": false,
    "text": "Greetings from Sinch"
  }
}

Image message

Accepted content types can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "image",
    "url": "https://example.com/image.jpg",
    "caption": "Example Image"
  }
}

Video message

Accepted content types can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "video",
    "url": "https://example.com/video.mp4",
    "caption": "Example Video",
    "provider": "your-bearer-provider"
  }
}

Document message

Accepted content types can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "document",
    "url": "https://example.com",
    "caption": "Example study",
    "filename": "document.pdf"
  }
}

Audio message

Accepted content types can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "audio",
    "url": "https://example.com/song.mp3"
  }
}

Location message

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "location",
    "lat": 55.7047,
    "lng": 13.191,
    "name": "Sinch Ideon Lund",
    "address": "Scheelevägen 17"
  }
}

Contacts message

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "city": "Menlo Park",
            "country": "United States",
            "country_code": "us",
            "state": "CA",
            "street": "1 Hacker Way",
            "type": "HOME",
            "zip": "94025"
          }
        ],
        "birthday": "2012-08-18",
        "emails": [
          {
            "email": "test@fb.com",
            "type": "WORK"
          }
        ],
        "name": {
          "first_name": "John",
          "formatted_name": "John Smith",
          "last_name": "Smith"
        },
        "org": {
          "company": "WhatsApp",
          "department": "Design",
          "title": "Manager"
        },
        "phones": [
          {
            "phone": "+1 (650) 555-1234",
            "type": "WORK",
            "wa_id": "16505551234"
          }
        ],
        "urls": [
          {
            "url": "https://www.facebook.com",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

Sticker message

Custom sticker must comply with WhatsApp requirements:

1. Each sticker should have a transparent background.
2. Stickers must be exactly 512x512 pixels.
3. Each sticker must be less than 100 KB.

Please note that WhatsApp doesn't support animated stickers.

Accepted content types can be found in the introduction.

JSON object parameters:

{
  "to": ["46732001122"],
  "message": {
    "type": "sticker",
    "url": "https://example.com/sticker.webp"
  }
}

Interactive message

Interactive messages give the recipient options to choose from. The choices are returned in callbacks.

JSON object parameters:

Button message

This message type provides the recipient with up to three buttons which can be pressed. A button press causes a response to be sent back in a callback. See Interactive button reply message

The button header has the following field:

The rest of the header fields are different for different header types.

• Text header

• Document header

• Video header

• Image header

The button body has the following field:

The button footer has the following field:

The button action has the following field:

Each button object has the following fields:

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "button",
      "header": {
        "type": "video",
        "url": "https://example.com/video.mp4"
      },
      "body": {
        "text": "Body text"
      },
      "footer": {
        "text": "Footer text"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "title": "Title 1",
            "id": "Id 1"
          },
          {
            "type": "reply",
            "title": "Title 2",
            "id": "Id 2"
          },
          {
            "type": "reply",
            "title": "Title 3",
            "id": "Id 3"
          }
        ]
      }
    }
  }
}

List message

This message type provides the recipient with a list of choices. Pressing one of the choices causes a response to be sent back in a callback. See Interactive list reply message

The list header has the following fields:

The list body has the following field:

The list footer has the following field:

The list action has the following fields:

Each list section has the following fields:

Each row object has the following field:

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "list",
      "header": {
        "type": "text",
        "text": "Header text"
      },
      "body": {
        "text": "Body text"
      },
      "footer": {
        "text": "Footer text"
      },
      "action": {
        "button": "Press me",
        "sections": [
          {
            "title": "Section 1",
            "rows": [
              {
                "title": "A row",
                "id": "ID 1",
                "description": "Description"
              }
            ]
          },
          {
            "title": "Section 2",
            "rows": [
              {
                "title": "Another row",
                "id": "ID 2",
                "description": "Description"
              }
            ]
          }
        ]
      }
    }
  }
}

Product message

This message type provides the recipient with information about a product in a product catalog. The recipient can respond with questions about a product or by placing an order for products.

The product message body has the following field:

The product message footer has the following field:

The product message action has the following fields:

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "product",
      "body": {
        "text": "Body text"
      },
      "footer": {
        "text": "Footer text"
      },
      "action": {
        "catalog_id": "catalogid",
        "product_retailer_id": "productretailerid",
      }
    }
  }
}

Find more product message examples here.

Product list message

This message type provides the recipient with a list of products in a product catalog. The recipient can respond with questions about a product or by placing an order for products.

The product list message header has the following fields:

The product list message body has the following field:

The product list message footer has the following field:

The product list message action has the following fields:

Each product list message section has the following fields:

Each product item object in a product_items array has the following field:

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "product_list",
      "header": {
        "type": "text",
        "text": "Header text"
      },
      "body": {
        "text": "Body text"
      },
      "action": {
        "catalog_id": "catalogid",
        "sections": [
          {
            "product_items": [
              {
                "product_retailer_id": "product1"
              },
              {
                "product_retailer_id": "product2"
              }
            ]
          }
        ]
      }
    }
  }
}

{
  "to": ["46732001122"],
  "message": {
    "type": "interactive",
    "message": {
      "type": "product_list",
      "header": {
        "type": "text",
        "text": "Header text"
      },
      "body": {
        "text": "Body text"
      },
      "footer": {
        "text": "Footer text"
      },
      "action": {
        "catalog_id": "catalogid",
        "sections": [
          {
            "title": "Section 1",
            "product_items": [
              {
                "product_retailer_id": "product1"
              },
              {
                "product_retailer_id": "product2"
              }
            ]
          },
          {
            "title": "Section 2",
            "product_items": [
              {
                "product_retailer_id": "product3"
              }
            ]
          }
        ]
      }
    }
  }
}

Find more product list message examples here.