Skip to content
API Documentation

Inbound Message

POST
/your-webhook-url
curl --request POST \
  --url https://api.contacta.mx/your-webhook-url \
  --header 'Content-Type: application/json' \
  --data '{ "type": "inbound", "payload": { "app": "5215589427963", "type": "message", "msisdn": "5215581234567", "added_on": "2023-12-04 22:19:24", "type_message": "image", "charge": 0.5, "payload": { "id": "E8977F4F1E3060F18ADBFE0E6D2DF6C4", "source": "5215581234567", "type": "image", "sender": { "phone": "5215581234567", "name": "5215581234567", "country_code": 52, "dial_code": "5581989356" }, "payload": { "caption": "", "url": "https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg", "contentType": "image/jpeg", "urlExpiry": 1701857964 } } } }'

Contacta.mx sends a POST request to your configured webhook URL when an inbound WhatsApp message is received on any of your agents.

This is not an endpoint you call — configure your webhook URL in the portal and implement it on your server to receive messages.

The inner payload.type_message field tells you what kind of content was received. The payload.payload object structure varies accordingly — see the schema for details.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Payload delivered to your webhook URL when an inbound WhatsApp message is received.

The outer type is always inbound. The inner payload.type_message indicates the type of content the user sent (text, image, audio, etc.).

object
type
required
string
Allowed values: inbound
payload
required
object
app
required

WhatsApp Business phone number of the receiving agent (E.164 without +)

string
type
required
string
Allowed values: message
msisdn
required

Sender’s phone number (E.164 without +)

string
added_on
required

Timestamp when the message was received by the platform

string format: date-time
type_message
required

Content type of the received message

string
Allowed values: text image audio video file location sticker contacts
charge

Cost charged for receiving this message

number format: float
payload
required

Message details — structure varies based on type_message

object
id
required

Unique message ID assigned by the platform

string
source
required

Sender’s phone number (E.164 without +)

string
type
required

Content type (mirrors type_message)

string
sender
required
object
phone
string
name

Sender’s WhatsApp display name

string
country_code
integer
dial_code
string
payload
required

Inner content payload — fields depend on type_message:

  • text: text (string)
  • image / video / sticker: url, caption, contentType, urlExpiry
  • audio / file: url, contentType, urlExpiry
  • location: longitude, latitude, name, address
object
text

Message text (present when type_message is text)

string
url

Temporary URL to the received media file

string format: uri
caption

Caption sent with the media (may be empty)

string
contentType

MIME type of the media file

string
urlExpiry

Unix timestamp when the media URL expires

integer
longitude

Longitude (present when type_message is location)

number format: float
latitude

Latitude (present when type_message is location)

number format: float
name

Location name (present when type_message is location)

string
address

Location address (present when type_message is location)

string
Example
{
  "type": "inbound",
  "payload": {
    "app": "5215589427963",
    "type": "message",
    "msisdn": "5215581234567",
    "added_on": "2023-12-04 22:19:24",
    "type_message": "image",
    "charge": 0.5,
    "payload": {
      "id": "E8977F4F1E3060F18ADBFE0E6D2DF6C4",
      "source": "5215581234567",
      "type": "image",
      "sender": {
        "phone": "5215581234567",
        "name": "5215581234567",
        "country_code": 52,
        "dial_code": "5581989356"
      },
      "payload": {
        "caption": "",
        "url": "https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg",
        "contentType": "image/jpeg",
        "urlExpiry": 1701857964
      }
    }
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Your server must return HTTP 200 to acknowledge receipt. Any other status code may trigger a retry.