Incoming SMS (MO)

Caution

For security reasons, please contact your Account Manager to provide you with an API host.

The host https://api.example.com not is a real endpoint.

POST

/your-webhook-url/mo

• Production

Contacta.mx sends a POST request to your configured webhook URL when an inbound SMS message (Mobile Originated) is received.

This is not an endpoint you call — configure your webhook URL through request to soporte@contacta.mx and implement this endpoint on your server to receive incoming messages.

Validating requests

Every webhook request includes the following headers to verify it originates from contacta.mx:

Header	Value
User-Agent	contacta.mx
x-contacta-time	Unix timestamp (seconds)
x-contacta-user	sha1(api_key)
x-contacta-signature	sha1(api_key + x-contacta-time)

Reject requests where the signature does not match or where x-contacta-time is older than your acceptable tolerance window (e.g. 60 seconds).

Parameters

Header Parameters

User-Agent

required

string

Allowed values: contacta.mx

contacta.mx

Always set to contacta.mx on webhook requests

x-contacta-time

required

integer

1750000000

Unix timestamp (seconds) of when the request was sent.

Use this together with x-contacta-signature to validate request freshness and prevent replay attacks.

x-contacta-user

required

string

a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

SHA1 hash of your API key.

Use this to identify which account sent the webhook.

x-contacta-signature

required

string

b6589fc6ab0dc82cf12099d1c2d40ab994e8410c

SHA1 hash of your API key concatenated with the timestamp from x-contacta-time.

Use this to verify the request authenticity:

expected = sha1(api_key + x-contacta-time)
valid    = expected == x-contacta-signature

Request Body ^required

Payload delivered to your webhook URL when an incoming SMS (MO) is received.

Either sms_id or short_code will be present depending on your account configuration:

• sms_id — when the message was received on a shared short code
• short_code — when the message was received on a dedicated short code

object

source_addr

required

Phone number of the person who sent the message (E.164 without +)

string

5218112345678

message

required

Text content of the incoming SMS

string

Hola, quiero más información

sms_id

Originating MT message ID. Present when the reply was received on a shared short code. Identifies which outgoing message this reply corresponds to.

string

MT-9f3a1b7c2d

short_code

Dedicated short code that received the message. Present when your account has a dedicated short code assigned.

string

40404

Examples

Reply received on shared short code

{
  "source_addr": "5218112345678",
  "message": "Hola, quiero más información",
  "sms_id": "MT-9f3a1b7c2d"
}

Message received on dedicated short code

{
  "source_addr": "5218112345678",
  "message": "STOP",
  "short_code": "40404"
}

Responses

200

Your server must return HTTP 200 to acknowledge receipt. Any other status code will trigger a retry from contacta.mx.

Examples

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

Bash

developer@developer:~#

curl -X POST "https://api.example.com/your-webhook-url/mo" \
    -H "Accept: application/json" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -H "User-Agent: value" \
  -H "x-contacta-time: value" \
  -H "x-contacta-user: value" \
  -H "x-contacta-signature: value" \
  -d '{"source_addr":"5218112345678","message":"Hola, quiero más información","sms_id":"MT-9f3a1b7c2d","short_code":"40404"}'

Node.js

example.js

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

  fetch("https://api.example.com/your-webhook-url/mo", {
    method: "POST",
    headers: {
  "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "User-Agent": "value",
  "x-contacta-time": "value",
  "x-contacta-user": "value",
  "x-contacta-signature": "value"
},
    body: JSON.stringify({
  "source_addr": "5218112345678",
  "message": "Hola, quiero más información",
  "sms_id": "MT-9f3a1b7c2d",
  "short_code": "40404"
})
  })
    .then(res => res.json())
    .then(console.log)
    .catch(console.error);

PHP

example.php

  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/your-webhook-url/mo",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Connection: keep-alive",
    "Content-Type: application/json",
    "User-Agent: value",
    "x-contacta-time: value",
    "x-contacta-user: value",
    "x-contacta-signature: value"
    ],
    CURLOPT_POSTFIELDS => json_encode({
  "source_addr": "5218112345678",
  "message": "Hola, quiero más información",
  "sms_id": "MT-9f3a1b7c2d",
  "short_code": "40404"
})
  ]);

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

C-Sharp

example.cs

  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/mo") {
    Content = new StringContent("{
  \"source_addr\": \"5218112345678\",
  \"message\": \"Hola, quiero más información\",
  \"sms_id\": \"MT-9f3a1b7c2d\",
  \"short_code\": \"40404\"
}", Encoding.UTF8, "application/json")
  };
  request.Headers.Add("Accept", "application/json");
request.Headers.Add("Connection", "keep-alive");
request.Headers.Add("Content-Type", "application/json");
request.Headers.Add("User-Agent", "value");
request.Headers.Add("x-contacta-time", "value");
request.Headers.Add("x-contacta-user", "value");
request.Headers.Add("x-contacta-signature", "value");
  var response = await client.SendAsync(request);
  var responseBody = await response.Content.ReadAsStringAsync();
  Console.WriteLine(responseBody);

Python

example.py

  import requests
  import json

  url = "https://api.example.com/your-webhook-url/mo"
  headers = {
    "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "User-Agent": "value",
  "x-contacta-time": "value",
  "x-contacta-user": "value",
  "x-contacta-signature": "value"
  }
  data = {
  "source_addr": "5218112345678",
  "message": "Hola, quiero más información",
  "sms_id": "MT-9f3a1b7c2d",
  "short_code": "40404"
}

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

Java

example.java

  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/mo");
      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");
    conn.setRequestProperty("User-Agent", "value");
    conn.setRequestProperty("x-contacta-time", "value");
    conn.setRequestProperty("x-contacta-user", "value");
    conn.setRequestProperty("x-contacta-signature", "value");

      String jsonInputString = "{\"source_addr\":\"5218112345678\",\"message\":\"Hola, quiero más información\",\"sms_id\":\"MT-9f3a1b7c2d\",\"short_code\":\"40404\"}";
      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);
    }
  }