Blocks Documentation

This documentation provides an overview of the different blocks that can be added to a channel template for the WhatsApp platform. Each block serves a specific purpose and can be customized to create rich and interactive conversations with users. The following blocks are available:

Text

Header, Body, or Footer Blocks

• Role: header, body, or footer

• Purpose: Displays text content in the header, body, or footer section of the message.

• Properties:

  • text: Specifies the text to be displayed. The maximum length varies depending on the role.

{
  "type": "text",
  "role": "body",
  "text": {
    "text": "Hey there!"
  },
  "id": "tY5sE17ZbfU8LmH0qRkOpN"
}

Images

Header Block

• Role: header

• Purpose: Displays an image in the header section of the message.

• Properties:

  • mediaUrl: The URL of the image to be displayed.

  • altText: Alternative text to be shown if the image cannot be loaded.

{
  "type": "image",
  "role": "header",
  "image": {
    "mediaUrl": "https://example.com/image.jpg",
    "altText": "Image Alt Text"
  },
  "id": "7vY1pgyRZ7ETflSK46d5qL"
}

Files

Header Block

• Role: header

• Purpose: Displays a file attachment in the header section of the message.

• Properties:

  • mediaUrl: The URL of the file to be attached.

  • contentType: The type of file, such as PDF, JPEG, PNG, or MP4.

  • filename: The name of the file.

  • altText: Alternative text to be shown if the file cannot be loaded.

{
  "type": "file",
  "role": "header",
  "file": {
    "mediaUrl": "https://example.com/file.pdf",
    "contentType": "application/pdf",
    "filename": "Sample File",
    "altText": "File Alt Text"
  },
  "id": "9B02RxTQq3UnLmY8EJgDKo"
}

Authentication body block

• Purpose: Specifically used for the authentication message type to provide users with their code and information around code expiration.

• Properties:

  • addSecurityDisclaimer: Specifies whether to include a security disclaimer.

  • expirationTime: The expiration time for the authentication process in days (1-90). Optional.

{
  "type": "authentication-body",
  "authenticationBody": {
    "addSecurityDisclaimer": true,
    "expirationTime": 30
  },
  "id": "rB523rS4PsGlt15NhwcZ8"
}

Actions

Link Action Block

• Purpose: Displays a text message with a link that users can interact with.

• Properties:

  • text: The text to be displayed as the message content.

  • url: The URL to which the link should navigate.

{
  "type": "link-action",
  "linkAction": {
    "text": "Click Here",
    "url": "https://example.com"
  },
  "id": "X7htGhJWu9l5dSe2rTqOZV"
}

Reply Action Block

• Purpose: Displays a text message with a reply option for users.

• Properties:

  • text: The text to be displayed as the message content.

  • payload: An optional payload to be sent back when the reply option is selected.

  • imageUrl: An optional image URL to be displayed alongside the text.

{
  "type": "reply-action",
  "replyAction": {
    "text": "Reply Button",
    "payload": "reply_payload",
    "imageUrl": "https://example.com/image.jpg"
  },
  "id": "aF5n1rS3DkGlm64IhOcX9P"
}

Authentication Action Block

• Purpose: Displays a button that users can click to copy the authentication code.

• Properties:

  • copyAuthenticationCodeText: The text to be displayed for copying the authentication code.

  • oneTap: An optional object representing the one-tap authentication configuration. Includes oneTapText, androidPackageName, and androidSignatureHash properties. Read more here.

{
  "type": "authentication-action",
  "authenticationAction": {
    "copyAuthenticationCodeText": "Copy Code",
    "oneTap": {
      "oneTapText": "One-Tap Authentication",
      "androidPackageName": "com.example.app",
      "androidSignatureHash": "signature_hash"
    }
  },
  "id": "p3F9tltd046dRbSjS56q2A"
}

Message types and block structures

There are 4 main message types supported by WhatsApp Approved templates. Each message type is made up of a block structure:

Message Type	Content block structure
Text message	Must contain text body (only 1 is allowed) Can contain only 1 text footer Can contain only 1 of the following headers: text | image | file header Can contain only 1 link action. Cannot be combined with reply actions. Can contain up to 3 reply actions. Cannot be combined with a link action.
Image message	Must contain text body (only 1 is allowed) Can contain only 1 image Can contain only 1 text footer Can contain only 1 link action. Cannot be combined with reply actions. Can contain up to 3 reply actions. Cannot be combined with a link action.
File message	Must contain text body (only 1 is allowed) Can contain only 1 file Can contain only 1 text footer Can contain only 1 link action. Cannot be combined with reply actions. Can contain up to 3 reply actions. Cannot be combined with a link action.
Authentication message	Must contain an authentication body Must contain an authentication action

Block IDs

Here are some guidelines and considerations regarding the IDs for blocks:

1. Uniqueness: Each block should have a unique ID within the conversation. This ensures that no two blocks have the same identifier, avoiding conflicts or ambiguity.

2. ID Format: IDs can be alphanumeric strings, often generated using unique identifiers, such as UUIDs (Universally Unique Identifiers). These IDs should be sufficiently long and complex to minimize the chance of collision.

3. ID Assignment: IDs can be assigned during the initial creation of the block.

{
  "type": "text",
  "role": "footer",
  "text": {
    "text": "Bye!"
  },
  "id": "cbA0XdmkFDAbJiGfS41kK9"
}

In the example above, the block has an ID of "cbA0XdmkFDAbJiGfS41kK9". This ID serves as a unique identifier for the block within the conversation. Other blocks in the conversation would have their own unique IDs.