Inbound Message Notifications

You will receive a notification when your business receives a message. The message object section below covers all the information you may receive about an incoming message. This section shows examples of text messages and location messages.

📘
Example: Text Message Received
The following is an example of a text message you received from a customer. See the text object section below for more information.

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
        }
    ],
    "messages": [
        {
            "from": "16315551234",
            "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "timestamp": "1518694235",
            "text": {
                "body": "Hello this is an answer"
            },
            "type": "text"
        }
    ]
}

📘
Example: Static Location Message Received
The following is an example of a message you received from a customer specifying their static location. See the location object section below for more information.

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
        }
    ],
    "messages": [
        {
            "from": "16315551234",
            "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "location": {
                "address": "Main Street Beach, Santa Cruz, CA",
                "latitude": 38.9806263495,
                "longitude": -131.9428612257,
                "name": "Main Street Beach",
                "url": "https://foursquare.com/v/4d7031d35b5df7744"
            },
            "timestamp": "1521497875",
            "type": "location"
        }
    ]
}

📘
Example: Contacts Message Received
The following is an example of a message you received from a customer specifying their contact information. See the contacts object section below for more information.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "contacts": [
        {
          "addresses": [
            {
              "city": "Menlo Park",
              "country": "United States",
              "country_code": "us",
              "state": "CA",
              "street": "1 Hacker Way",
              "type": "WORK",
              "zip": "94025"
            }
          ],
          "birthday": "2012-08-18",
          "contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHR...",
          "emails": [
            {
              "email": "kfish@fb.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "AIM",
              "user_id": "kfish"
            }
          ],
          "name": {
            "first_name": "Kerry",
            "formatted_name": "Kerry Fisher",
            "last_name": "Fisher"
          },
          "org": {
            "company": "Facebook"
          },
          "phones": [
            {
              "phone": "+1 (940) 555-1234",
              "type": "CELL"
            },
            {
              "phone": "+1 (650) 555-1234",
              "type": "WORK",
              "wa_id": "16505551234"
            }
          ],
          "urls": [
            {
              "url": "https://www.facebook.com",
              "type": "WORK"
            }
          ]
        }
      ],
      "from": "16505551234",
      "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
      "timestamp": "1537248012",
      "type": "contacts"
    }
  ]
}

📘
Example: Unknown Message Received
Beginning with v2.21.3 it is possible to receive an unknown callback notification. The following is an example of a message you received from a customer that is not supported.

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
        }
    ],
    "messages": [
        {
            "errors": [
                {
                    "code": 501,
                    "details": "Message type is not currently supported",
                    "title": "Unknown message type"
                }
            ],
            "from": "16315551234",
            "id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
            "timestamp": "1531933468",
            "type": "unknown"
        }
    ]
}

Inbound Media Message Notifications

When a message with media is received, the WhatsApp Business API Client will download the media. A notification is sent to your Webhook once the media is downloaded. This message contains information that identifies the media object and enables you to find and retrieve the object. Use the Media endpoint with the media's id to retrieve the media. This section shows examples of messages that are received with media.

📘
Example: Message with Image Received
The following is an example inbound message that contains an image.

Note : The caption field is optional for media messages. It is only included if the user has set a caption.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image": {
        "file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
        "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
        "mime_type": "image/jpeg",
        "sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
        "caption": "Check out my new phone!"
      },
      "timestamp": "1521497954",
      "type": "image"
    }
  ]
}

📘
Example: Message with Document Received
The following is an example inbound message that contains a document. See the media object
section below to learn more about the different media types.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "timestamp": "1522189546",
      "type": "document",
      "document": {
        "caption": "80skaraokesonglistartist",
        "file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbdb2f68f798e33",
        "id": "fc233119-733f-49c-bcbd-b2f68f798e33",
        "mime_type": "application/pdf",
        "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e"
      }
    }
  ]
}

📘
Example: Message with Voice Message Received
The following is an example inbound message that contains a voice message. See the media object section below to learn more about the different media types.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "timestamp": "1521827831",
      "type": "voice",
      "voice": {
        "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
        "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

📘
Example: Message with Sticker Received
The following is an example inbound message that contains a sticker. See the media object section below to learn more about the different media types.

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher"
      },
      "wa_id": "16315551234"
    }
  ],
    "messages": [
        {
            "from": "16315551234",
            "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
            "timestamp": "1521827831",
            "type": "sticker",
            "sticker": {
                "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
                "metadata": {
                    "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                    "sticker-pack-name": "Happy New Year",
                    "sticker-pack-publisher": "Kerry Fisher",
                    "emojis": [
                        "🐥",
                        "😃"
                    ],
                    "ios-app-store-link": "https://apps.apple.com/app/id3133333",
                    "android-app-store-link": "https://play.google.com/store/apps/details?id=com.example",
                    "is-first-party-sticker": 0 | 1 # integer
                },
                "mime_type": "image/webp",
                "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
            }
        }
    ]
}

📘
Example: Received Frequently Forwarded Message
Beginning with v2.29.1 it is possible to see if a message you received has been forwarded or is frequently forwarded. The following is an example of a message that you received, that was forwarded multiple times.

{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16315551234"
        }
    ],
    "messages": [
        {
            "context": {
                "frequently_forwarded": true
            },
            "from": "16315558011",
            "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
            "timestamp": "1593068225",
            "type": "video",
            "video": {
                "id": "e144be57-12b1-4035-a520-703fcc87ef45",
                "mime_type": "video/mp4",
                "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
            }
        }
    ]
}