Inbound Message

POST

/your-webhook-url

Production

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 Body^required

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

inbound

payload

required

object

app

required

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

string

5215589427963

type

required

string

Allowed values: message

message

msisdn

required

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

string

5215581234567

added_on

required

Timestamp when the message was received by the platform

string format: date-time

2023-12-04 22:19:24

type_message

required

Content type of the received message

string

Allowed values: text image audio video file location sticker contacts

image

charge

Cost charged for receiving this message

number format: float

0.5

payload

required

Message details — structure varies based on type_message

object

required

Unique message ID assigned by the platform

string

E8977F4F1E3060F18ADBFE0E6D2DF6C4

source

required

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

string

5215581234567

type

required

Content type (mirrors type_message)

string

image

sender

required

object

phone

string

5215581234567

name

Sender’s WhatsApp display name

string

John Doe

country_code

integer

dial_code

string

5581989356

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

Hola, quiero más información

url

Temporary URL to the received media file

string format: uri

https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg

caption

Caption sent with the media (may be empty)

string

contentType

MIME type of the media file

string

image/jpeg

urlExpiry

Unix timestamp when the media URL expires

integer

1701857964

longitude

Longitude (present when type_message is location)

number format: float

-99.1332

latitude

Latitude (present when type_message is location)

number format: float

19.4326

name

Location name (present when type_message is location)

string

Ciudad de México

address

Location address (present when type_message is location)

string

CDMX, Mexico

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

200

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

Examples

Useful for guiding users to view code examples in different developer languages.

curl -X POST "https://api.example.com/your-webhook-url" \
    -H "Accept: application/json" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{"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":"John Doe","country_code":52,"dial_code":"5581989356"},"payload":{"text":"Hola, quiero más información","url":"https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg","caption":"","contentType":"image/jpeg","urlExpiry":1701857964,"longitude":-99.1332,"latitude":19.4326,"name":"Ciudad de México","address":"CDMX, Mexico"}}}}'

  const fetch = require('node-fetch');

  fetch("https://api.example.com/your-webhook-url", {
    method: "POST",
    headers: {
  "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json"
},
    body: JSON.stringify({
  "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": "John Doe",
        "country_code": 52,
        "dial_code": "5581989356"
      },
      "payload": {
        "text": "Hola, quiero más información",
        "url": "https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg",
        "caption": "",
        "contentType": "image/jpeg",
        "urlExpiry": 1701857964,
        "longitude": -99.1332,
        "latitude": 19.4326,
        "name": "Ciudad de México",
        "address": "CDMX, Mexico"
      }
    }
  }
})
  })
    .then(res => res.json())
    .then(console.log)
    .catch(console.error);

  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/your-webhook-url",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Connection: keep-alive",
    "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode({
  "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": "John Doe",
        "country_code": 52,
        "dial_code": "5581989356"
      },
      "payload": {
        "text": "Hola, quiero más información",
        "url": "https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg",
        "caption": "",
        "contentType": "image/jpeg",
        "urlExpiry": 1701857964,
        "longitude": -99.1332,
        "latitude": 19.4326,
        "name": "Ciudad de México",
        "address": "CDMX, Mexico"
      }
    }
  }
})
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>

  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.POST, "https://api.example.com/your-webhook-url") {
    Content = new StringContent("{
  \"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\": \"John Doe\",
        \"country_code\": 52,
        \"dial_code\": \"5581989356\"
      },
      \"payload\": {
        \"text\": \"Hola, quiero más información\",
        \"url\": \"https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg\",
        \"caption\": \"\",
        \"contentType\": \"image/jpeg\",
        \"urlExpiry\": 1701857964,
        \"longitude\": -99.1332,
        \"latitude\": 19.4326,
        \"name\": \"Ciudad de México\",
        \"address\": \"CDMX, Mexico\"
      }
    }
  }
}", Encoding.UTF8, "application/json")
  };
  request.Headers.Add("Accept", "application/json");
request.Headers.Add("Connection", "keep-alive");
request.Headers.Add("Content-Type", "application/json");
  var response = await client.SendAsync(request);
  var responseBody = await response.Content.ReadAsStringAsync();
  Console.WriteLine(responseBody);

  import requests
  import json

  url = "https://api.example.com/your-webhook-url"
  headers = {
    "Accept": "application/json",
  "Connection": "keep-alive",
  "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": "John Doe",
        "country_code": 52,
        "dial_code": "5581989356"
      },
      "payload": {
        "text": "Hola, quiero más información",
        "url": "https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg",
        "caption": "",
        "contentType": "image/jpeg",
        "urlExpiry": 1701857964,
        "longitude": -99.1332,
        "latitude": 19.4326,
        "name": "Ciudad de México",
        "address": "CDMX, Mexico"
      }
    }
  }
}

  response = requests.post(url, headers=headers, json=data)
  print(response.text)

  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;

  public class ApiExample {
    public static void main(String[] args) throws Exception {
      URL url = new URL("https://api.example.com/your-webhook-url");
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      conn.setRequestProperty("Accept", "application/json");
    conn.setRequestProperty("Connection", "keep-alive");
    conn.setRequestProperty("Content-Type", "application/json");

      String jsonInputString = "{\"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\":\"John Doe\",\"country_code\":52,\"dial_code\":\"5581989356\"},\"payload\":{\"text\":\"Hola, quiero más información\",\"url\":\"https://storage.onechat.mx/8141621060/2502100f-a62d-4e72-8137-ab1a22a1fa79.jpeg\",\"caption\":\"\",\"contentType\":\"image/jpeg\",\"urlExpiry\":1701857964,\"longitude\":-99.1332,\"latitude\":19.4326,\"name\":\"Ciudad de México\",\"address\":\"CDMX, Mexico\"}}}}";
      try(OutputStream os = conn.getOutputStream()) {
          byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
          os.write(input, 0, input.length);
      }

      int code = conn.getResponseCode();
      System.out.println("Response code: " + code);
    }
  }

Inbound Message

Request Body required

Example

Responses

200

Examples

Request Body^required