Skip to main content

Unsupported messages webhook reference | Developer Documentation

Unsupported messages webhook reference

Updated: Mar 20, 2026
This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for unsupported messages.

Triggers

    A WhatsApp user sends a message type not supported by Cloud API.You use the API to send a message to a number already in use with the API. In this case, the webhook is sent to the owner of the recipient number.A WhatsApp user messages a business that has been onboarded with a WhatsApp Business app phone number, for the first time. This is especially common when users tap one of the business’s ads that click to WhatsApp⁠ and immediately send a message.

    Syntax

    {
      "object": "whatsapp_business_account",
      "entry": [
        {
          "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
          "changes": [
            {
              "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                  "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                  "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
                },
                "contacts": [
                  {
                    "profile": {
                      "name": "<WHATSAPP_USER_PROFILE_NAME>"
                    },
                    "wa_id": "<WHATSAPP_USER_ID>",
                    "identity_key_hash": "<IDENTITY_KEY_HASH>" <!-- only included if identity change check enabled -->
                  }
                ],
                "messages": [
                  {
                    "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                    "id": "<WHATSAPP_MESSAGE_ID>",
                    "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                    "errors": [
                      {
                        "code": <ERROR_CODE>,
                        "title": "<ERROR_TITLE>",
                        "message": "<ERROR_MESSAGE>",
                        "error_data": {
                          "details": "<ERROR_DETAILS>"
                        }
                      }
                    ],
                    "type": "unsupported",
                    "unsupported": {
                    "type": <UNSUPPORTED_TYPE>
                  }
                  }
                ]
              },
              "field": "messages"
            }
          ]
        }
      ]
    }
    Parameters
    
Placeholder

Description

Example value

    <BUSINESS_DISPLAY_PHONE_NUMBER>
    String
    Business display phone number.
    15550783881
    <BUSINESS_PHONE_NUMBER_ID>
    String
    Business phone number ID.
    106540352242922
    <IDENTITY_KEY_HASH>
    String
    Identity key hash. Only included if you have enabled the identity change check feature.
    DF2lS5v2W6x=
    <ERROR_CODE>
    The error code. Possible values:
      131051 — Cloud API does not support the message type.131060 — The message is currently unavailable. This typically occurs when a WhatsApp user messages a business onboarded with a WhatsApp Business app phone number, for the first time.
      131051
      <ERROR_DETAILS>
      A human-readable description of the error.
      Message type is currently not supported.
      <ERROR_MESSAGE>
      A human-readable error message. Same as ERROR_TITLE.
      Message type unknown
      <ERROR_TITLE>
      A human-readable error title. Possible values:
        Message type unknown — Corresponds to error code 131051.This message is currently unavailable. — Corresponds to error code 131060.
        Message type unknown
        <UNSUPPORTED_TYPE>
        Contains the type of message that is unsupported.
        Values can be:
        errors
        gif
        group_invite
        hsm
        image
        interactive
        keep_in_chat
        link_preview
        list
        location
        media_placeholder
        order
        pin
        poll_creation
        poll_update
        product
        reaction
        poll_update
        <WEBHOOK_TRIGGER_TIMESTAMP>
        String
        Unix timestamp indicating when the webhook was triggered.
        1739321024
        <WHATSAPP_BUSINESS_ACCOUNT_ID>
        String
        WhatsApp Business Account ID.
        102290129340398
        <WHATSAPP_MESSAGE_ID>
        String
        WhatsApp message ID.
        wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=
        <WHATSAPP_USER_ID>
        String
        WhatsApp user ID. Note that a WhatsApp user’s ID and phone number may not always match.
        16505551234
        <WHATSAPP_USER_PHONE_NUMBER>
        String
        WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user’s phone number and ID may not always match.
        +16505551234
        <WHATSAPP_USER_PROFILE_NAME>
        String
        WhatsApp user’s name as it appears in their profile in the WhatsApp client.
        Sheena Nelson
        Example
        The following example shows a webhook triggered by a WhatsApp user sending an unsupported message type (error code 131051). For unavailable messages (error code 131060), the payload structure is the same but the errors object values differ — see the ERROR_CODE parameter for details.
        {
        "object": "whatsapp_business_account",
        "entry": [
            {
        "id": "102290129340398",
        "changes": [
                {
        "value": {
        "messaging_product": "whatsapp",
        "metadata": {
        "display_phone_number": "15550783881",
        "phone_number_id": "106540352242922"
                    },
        "contacts": [
                      {
        "profile": {
        "name": "Sheena Nelson"
                        },
        "wa_id": "16505551234"
                      }
                    ],
        "messages": [
                      {
        "from": "16505551234",
        "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
        "timestamp": "1750090702",
        "errors": [
                          {
        "code": 131051,
        "title": "Message type unknown",
        "message": "Message type unknown",
        "error_data": {
        "details": "Message type is currently not supported."
                            }
                          }
                        ],
        "type": "unsupported",
        "unsupported": {
        "type": "edit"
            }
                      }
                    ]
                  },
        "field": "messages"
                }
              ]
            }
          ]
        }
        
    
                
        
        
        
    
        
        
        
            
        
                
                
        
                    
                    
                
        
            
        
            
            
        
                                            
        
        
        
    
        

    

        
    
        

    
            
        
            
        

    
        
        
        
            
            
        
        
            
        

    
        
        
        
                    
        

        
        No comments to display
        

            
        

    

    

                    
        
        
        
                
        
        
        
    
        

    
        

    
    
        
        
        
             Back to top