Events

message.received

View as Markdown

Emitted when an inbound SMS arrives on one of your Dial numbers. This is the event you wait for when receiving a one-time code or any inbound SMS reply.

Schema

Shares the common event envelope (id, object, type, version, createdAt, relatedObject). relatedObject is { id: <messageId>, type: "message", url: null } — messages have no get-by-id endpoint yet. The data payload:

data fieldTypeDescription
messageIdstringDial-issued ID for the message. Matches the id returned by GET /api/v1/messages.
fromstringSender phone number, E.164.
tostringYour Dial number that received the message, E.164.
channelstringThe channel the message arrived on: "sms", "imessage", or "rcs".
bodystringMessage text.
mediaarrayMedia attachments (MMS), in received order. Empty for plain SMS. Each item: id (public media ID), url (stable unauthenticated Dial URL serving the media — safe to fetch or render immediately), contentType (MIME type), originalUrl (the carrier’s source URL).
replyToIdstring | nullOn iMessage numbers, when the inbound message is a threaded reply or a reaction targeting one of your messages: the targeted message’s ID. Null for ordinary messages, or when the target isn’t a message on your account.
reactionstring | nullOn iMessage numbers, when the inbound message is a reaction (e.g. a Tapback): the reaction’s emoji. body is empty for reactions. Null for ordinary messages and threaded replies.
sourcestring"external" for messages delivered by a carrier; "internal" for messages synthesized by Dial (e.g. test injections). Filter on "external" if you only care about real inbound traffic.

Example

1{
2  "id": "evt_3f9a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90",
3  "object": "event",
4  "type": "message.received",
5  "version": 1,
6  "createdAt": "2026-05-28T14:32:08.412Z",
7  "relatedObject": { "id": "msg_01HW3X7P5QF6K2YQ9YJ7Q8R5N3", "type": "message", "url": null },
8  "data": {
9    "messageId": "msg_01HW3X7P5QF6K2YQ9YJ7Q8R5N3",
10    "from": "+14155550123",
11    "to": "+14155559876",
12    "channel": "sms",
13    "body": "Your verification code is 123456",
14    "media": [
15      {
16        "id": "a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30",
17        "url": "https://getdial.ai/public-media/a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30.jpg",
18        "contentType": "image/jpeg",
19        "originalUrl": "https://api.twilio.com/2010-04-01/Accounts/AC…/Messages/MM…/Media/ME…"
20      }
21    ],
22    "replyToId": null,
23    "reaction": null,
24    "source": "external"
25  }
26}

When it fires

  • Every time a carrier delivers an SMS to one of your Dial numbers.
  • Once per inbound message — no retries on the stream itself.
  • Internal test traffic (from dashboard or /api/v1/test/* helpers) carries data.source: "internal"; ignore those unless you’re explicitly testing.