Reply to a message | Dial — Communication Stack for AI Agents

{
  "message": {
    "id": "string",
    "phoneNumberId": "string",
    "from": "+14155550123",
    "to": "+14155559876",
    "body": "string",
    "direction": "inbound",
    "channel": "sms",
    "service": "imessage",
    "status": "delivered",
    "statusError": null,
    "media": [
      {
        "id": "a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30",
        "url": "https://getdial.ai/public-media/a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30.jpg",
        "contentType": "image/jpeg",
        "originalUrl": "https://your-cdn.example.com/summary.png"
      }
    ],
    "replyToId": null,
    "reaction": null,
    "createdAt": "2024-01-15T09:30:00Z"
  }
}

Sends a threaded reply or a reaction targeted at an existing message.

The sender is derived from the target message. The reply goes out from the Dial number the target message belongs to, to the other party of that message — there is no to or fromNumberId. A reply always stays in the conversation the target message is part of.

The request carries exactly one of:

body — a text reply. On iMessage numbers it is delivered as a native threaded reply (quoting the target message) when the recipient supports threads, and as a regular message otherwise. On standard numbers it is delivered as a regular SMS.
reaction — a reaction to the target message: one of the six reaction names (love, like, dislike, laugh, emphasize, question) or a single emoji (one visible symbol — skin-tone and multi-person emoji count as one; anything else is rejected with 400). On iMessage numbers the reaction is delivered natively (a Tapback). When the recipient can only receive SMS — including everything sent from standard numbers — an emoji reaction is delivered as a regular message whose body is the emoji, and a reaction name is rejected with 400 (names have no SMS rendering; send an emoji instead).

Targets. Any message on the account can be targeted, with one current restriction: on iMessage numbers the target must be an inbound message — replying to your own sent messages isn’t supported on those numbers yet. Standard numbers accept targets in both directions. A reaction cannot itself be the target — replying or reacting to a reaction is rejected with 400.

The created message is recorded like any outbound message and billed the same as Send a message. Its replyToId points at the target message; reaction carries the reaction string when one was sent (a reaction delivered natively has an empty body; one delivered as a regular message carries the emoji in body too).

Not idempotent — retrying a failed request can send a duplicate reply. On an ambiguous failure, confirm via List messages before re-sending.

Sends a threaded reply or a reaction targeted at an existing message. **The sender is derived from the target message.** The reply goes out from the Dial number the target message belongs to, to the other party of that message — there is no `to` or `fromNumberId`. A reply always stays in the conversation the target message is part of. The request carries **exactly one** of: - `body` — a text reply. On iMessage numbers it is delivered as a native threaded reply (quoting the target message) when the recipient supports threads, and as a regular message otherwise. On standard numbers it is delivered as a regular SMS. - `reaction` — a reaction to the target message: one of the six reaction names (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) or a **single emoji** (one visible symbol — skin-tone and multi-person emoji count as one; anything else is rejected with `400`). On iMessage numbers the reaction is delivered natively (a Tapback). When the recipient can only receive SMS — including everything sent from standard numbers — an **emoji** reaction is delivered as a regular message whose body is the emoji, and a reaction **name** is rejected with `400` (names have no SMS rendering; send an emoji instead). **Targets.** Any message on the account can be targeted, with one current restriction: on iMessage numbers the target must be an **inbound** message — replying to your own sent messages isn't supported on those numbers yet. Standard numbers accept targets in both directions. A **reaction cannot itself be the target** — replying or reacting to a reaction is rejected with `400`. The created message is recorded like any outbound message and billed the same as Send a message. Its `replyToId` points at the target message; `reaction` carries the reaction string when one was sent (a reaction delivered natively has an empty `body`; one delivered as a regular message carries the emoji in `body` too). Not idempotent — retrying a failed request can send a duplicate reply. On an ambiguous failure, confirm via List messages before re-sending.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Path parameters

messageIdstringRequired

ID of the message to reply or react to (see List messages).

Request

This endpoint expects an object.

bodystringOptional

Reply text. Exactly one of body and reaction is required. On a standard number the same content-size limit as Send a message applies (1530 characters, or 670 if the text uses characters outside the basic SMS alphabet); a longer reply is rejected with 400.

reactionstringOptional

Reaction to send: love, like, dislike, laugh, emphasize, question, or a single emoji. Exactly one of body and reaction is required.

Response

Reply queued. The created message, with replyToId set to the target message’s ID.

messageobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

429

Too Many Requests Error

Sends a threaded reply or a reaction targeted at an existing message.

The request carries exactly one of:

body — a text reply. On iMessage numbers it is delivered as a native threaded reply (quoting the target message) when the recipient supports threads, and as a regular message otherwise. On standard numbers it is delivered as a regular SMS.
reaction — a reaction to the target message: one of the six reaction names (love, like, dislike, laugh, emphasize, question) or a single emoji (one visible symbol — skin-tone and multi-person emoji count as one; anything else is rejected with 400). On iMessage numbers the reaction is delivered natively (a Tapback). When the recipient can only receive SMS — including everything sent from standard numbers — an emoji reaction is delivered as a regular message whose body is the emoji, and a reaction name is rejected with 400 (names have no SMS rendering; send an emoji instead).

Not idempotent — retrying a failed request can send a duplicate reply. On an ambiguous failure, confirm via List messages before re-sending.

$	curl -X POST https://api.getdial.ai/api/v1/messages/messageId/reply \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'