This is the current API V1 documentation. Explore our API V2 beta if you’d like to test new features.

Docs

Inbound Message Signatureinbound-message-signature

Each messaging webhook event that we send you will include a Telnyx signature. This signature allows you to validate that the webhooks were not sent by a third-party. Check out the receiving messages guide to set up a webhook for receiving SMS and MMS to a number.

Inbound Text Messageinbound-text-message

Let's imagine that you have the following set up:

phone number: +13125550001
incoming webhook URL: https://example.com/inbox/7420
secret: rq789onm321yxzkjihfEdcAm

Received by Telnyxreceived-by-telnyx

When Telnyx receives a message intended for your phone number the process outlined below is followed:

  1. 1Because you configured the incoming webhook, Telnyx builds the request payload from the received message attaching a unique ID.

Request payload:

{
  "sms_id":"834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "direction": "inbound",
  "from": "+13129450002",
  "to": "+13125550001",
  "body": "Hello!"
}
  1. 2To generate the signature, we first build the hash function's input by concatenating:
  • The [currentTelnyx Developers] Unix time in seconds
  • A period (.)
  • The raw message body of the request payload.

A more detailed explanation can be found in our signature generation documentation.

Retrieving the current Unix time in seconds, as an ASCII encoded string, in an interactive Python 3 interpreter:

>>> from datetime import datetime
>>> str(int(datetime.utcnow().timestamp())).encode('ascii')
b'1520983646'

Example hash function input:

1520983646.{
  "sms_id":"834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "direction": "inbound",
  "from": "+13129450002",
  "to": "+13125550001",
  "body": "Hello!"
}
  1. 3We then generate an HMAC-SHA256Telnyx Developers signature for this (the above) using the Messaging Profile secret.

In this example, the base64-encoded result is:

WlEXoEsHH2RMgy2x8eyvg10JlMBco0s51fdNpMORF00=

Delivered to Youdelivered-to-you

The same timestamp that is used in the body is then used to build the value of the X-Telnyx-Signature header. t= is prepended to the timestamp and h= to the signature, resulting in the below:

X-Telnyx-Signature: t=1520983646,h=WlEXoEsHH2RMgy2x8eyvg10JlMBco0s51fdNpMORF00=

When you receive the webhook notification for this message, you can take the request's payload and Messaging Profile secret and follow the same process to generate the signature. By comparing your result to the value included in the X-Telnyx-Signature header, you can verify that the webhook did in fact come from Telnyx.

Inbound MMSinbound-mms

When Telnyx receives an MMS intended for your phone number, the message will include an extra media field.

For instance, an MMS was sent to the same telephone number above. The payload could look like the following:

{
  "sms_id": "2c41e477-69b0-4c03-b91d-3d4a1e8f2c3b",
  "from": "+13129450002",
  "to": "+13125550001",
  "direction": "inbound",
  "body": "Hello!",
  "media": [
    {
      "url": "https://example.com/media/LONG_RANDOM_STRING.jpeg",
      "content_type": "image/jpeg",
      "hash_sha256": "sha256 hash",
      "size": 123456
    }
  ]
}

Validate the signature using the same process that is described above. The media will be available for 30 days. The URL does not require authentication; it is masked by the long unique ID. For sensitive media, take care to not inadvertently leak the URL.