JSON format

JSON formats to send the multiple types of messages supported by WhatsApp providers in uContact.

Content

1 Contact
2 Interactive
- - 2.1.1 Action Object
  - 2.1.2 Body Object
  - 2.1.3 Header Object
  - 2.1.4 Section Object
- 2.2 Location Object
- 2.3 Media Object
3 Product
- 3.1 Single Product
- 3.2 Multi Product
- 3.3 List
- 3.4 Reply Button
4 Template

Contact

Name	Description

Name

Description

addresses

object

Optional.

Full contact address(es) formatted as an addresses object. The object can contain the following fields:

streetstring – Optional. Street number and name.

citystring – Optional. City name.

statestring – Optional. State abbreviation.

zipstring – Optional. ZIP code.

countrystring – Optional. Full country name.

country_codestring – Optional. Two-letter country abbreviation.

typestring – Optional. Standard values are HOME and WORK.

birthday

Optional.

YYYY-MM-DD formatted string.

emails

object

Optional.

Contact email address(es) formatted as an emails object. The object can contain the following fields:

emailstring – Optional. Email address.

typestring – Optional. Standard values are HOME and WORK.

name

object

Required.

Full contact name formatted as a name object. The object can contain the following fields:

formatted_namestring – Required. Full name, as it normally appears.

first_namestring – Optional*. First name.

last_namestring – Optional*. Last name.

middle_namestring – Optional*. Middle name.

suffixstring – Optional*. Name suffix.

prefixstring – Optional*. Name prefix.

*At least one of the optional parameters needs to be included along with the formatted_name parameter.

org

object

Optional.

Contact organization information formatted as an org object. The object can contain the following fields:

companystring – Optional. Name of the contact's company.

departmentstring – Optional. Name of the contact's department.

titlestring – Optional. Contact's business title.

phones

object

Optional.

Contact phone number(s) formatted as a phone object. The object can contain the following fields:

phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number.

typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK.

wa_idstring – Optional. WhatsApp ID.

urls

object

Optional.

Contact URL(s) formatted as a urls object. The object can contain the following fields:

urlstring – Optional. URL.

typestring – Optional. Standard values are HOME and WORK.

{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
}

Interactive

Name	Description

Name

Description

action

object

Required.

Action you want the user to perform after reading the message.

body

object

Optional for type product. Required for other message types.

An object with the body of the message.

The body object contains the following field:

textstring – Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.

footer

object

Optional. An object with the footer of the message.

The footer object contains the following field:

textstring – Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length: 60 characters.

header

object

Required for type product_list. Optional for other types.

Header content displayed on top of a message. You cannot set a header if your interactive object is of product type. See header object for more information.

type

object

Required.

The type of interactive message you want to send. Supported values:

button: Use it for Reply Buttons.
list: Use it for List Messages.
product: Use for Single Product Messages.
product_list: Use for Multi-Product Messages.

The following objects are nested inside the interactive object:

Action Object

Name	Description

Name

Description

button

string

Required for List Messages.

Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.

Maximum length: 20 characters.

buttons

array of objects

Required for Reply Buttons.

A button object can contain the following parameters:

type: only supported type is reply (for Reply Button)
title: Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.
id: Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters.

You can have up to 3 buttons. You cannot have leading or trailing spaces when setting the ID.

catalog_id

string

Required for Single Product Messages and Multi-Product Messages.

Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the Meta Commerce Manager.

product_retailer_id

string

Required for Single Product Messages and Multi-Product Messages.

Unique identifier of the product in a catalog.

To get this ID go to Meta Commerce Manager and select your Meta Business account. You will see a list of shops connected to your account. Click the shop you want to use. On the left-side panel, click Catalog > Items, and find the item you want to mention. The ID for that item is displayed under the item's name.

sections

array of objects

Required for List Messages and Multi-Product Messages.

Array of section objects. Minimum of 1, maximum of 10. See section object.

Body Object

Nombre	Descripción

Nombre	Descripción
`type`	Obligatorio para las plantillas de mensaje. Tipo de mensaje que se envía. Opciones: `text`: opción predeterminada `image` `audio` `document` `template`: usa esta opción para enviar un mensaje de plantilla multimedia. `hsm`
`to`	Obligatorio. Identificador de WhatsApp al que se enviará el mensaje.
`ttl` Quedará obsoleto en la versión `v2.35`.	Opcional. A partir de la versión `v2.21.3`: duración del tiempo de vida (TTL). Valor predeterminado: 7 días Otras opciones: Las duraciones mínima y máxima compatibles oscilan entre 1 y 30 días (ambos valores incluidos). Acepta una cadena con el formato de duración ISO-8601 o, simplemente, en segundos. Las duraciones se deben especificar con un múltiplo exacto de días. Cualquier otro valor se redondea automáticamente al día más próximo. Consulta la sección del objeto `ttl` para obtener más información.
`recipient_type`	Opcional. Valor:`individual`
`template`	Obligatorio para los mensajes de tipo `template`. Contiene toda la información de la plantilla.
`hsm`	Obligatorio para las plantillas de mensaje. Elemento que incluye el contenido del mensaje. Indica que el mensaje está bien estructurado. Los parámetros incluidos proporcionan la estructura.

Header Object

Name	Description

Name

Description

document

object

Required if type is set to document.

Contains the media object for this document.

image

object

Required if type is set to image.

Contains the media object for this image.

text

string

Required if type is set to text.

Text for the header. Formatting allows emojis, but not markdown.

Maximum length: 60 characters.

type

string

Required.

The header type you would like to use. Supported values:

text: Used for List Messages, Reply Buttons, and Multi-Product Messages.
video: Used for Reply Buttons.
image: Used for Reply Buttons.
document: Used for Reply Buttons.

video

object

Required if type is set to video.

Contains the media object for this video.

Section Object

Name	Description

Name

Description

product_items

array of objects

Required for Multi-Product Messages.

Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.

Each product object contains the following field:

product_retailer_idstring – Required for Multi-Product Messages. Unique identifier of the product in a catalog. To get this ID, go to the Meta Commerce Manager, select your account and the shop you want to use. Then, click Catalog > Items, and find the item you want to mention. The ID for that item is displayed under the item's name.

rows

array of objects

Required for List Messages.

Contains a list of rows. You can have a total of 10 rows across your sections.

Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional.

Example:

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

title

string

Required if the message has more than one section.

Title of the section.

Maximum length: 24 characters.

Location Object

Name	Description

Name	Description
`longitude`	Required. Longitude of the location.
`latitude`	Required. Latitude of the location.
`name`	Optional. Name of the location.
`address`	Optional. Address of the location. Only displayed if `name` is present.

Media Object

See Get Media ID for information on how to get the ID of your media object. For information about supported media types for Cloud API, see Supported Media Types.

Name	Description

Name

Description

id

string

Required when type is audio, document, image, sticker, or video and you are not using a link.

The media object ID. Do not use this field when message type is set to text.

link

string

Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server).

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

Do not use this field when message type is set to text.

Cloud API users only:

See Media HTTP Caching if you would like us to cache the media asset for future messages.
When we request the media asset from your server you must indicate the media's MIME type by including the Content-Type HTTP header. For example: Content-Type: video/mp4. See Supported Media Types for a list of supported media and their MIME types.

filename

string

Optional.

Describes the filename for the specific document. Use only with document media.

The extension of the filename will specify what format the document is displayed as in WhatsApp.

provider

string

Optional. Only used for On-Premises API.

This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

Product

Single Product

{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "product_retailer_id": "ID_TEST_ITEM_1"
     }
   }
 }

Multi Product

List

Reply Button

Template

Name	Description

Name

Description

name

Required.

Name of the template.

language

object

Required.

Contains a language object. Specifies the language the template may be rendered in.

The language object can contain the following fields:

policystring – Required. The language policy the message should follow. The only supported option is deterministic. See Language Policy Options.

codestring – Required. The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). For all codes, see Supported Languages.

components

array of objects

Optional.

Array of components objects containing the parameters of the message.

namespace

Optional. Only used for On-Premises API.

Namespace of the template.