---
title: "Reply to a message"
method: POST
path: "/api/v1/messages/{messageId}/reply"
tags: ["messages"]
---

# Reply to a message

`POST /api/v1/messages/{messageId}/reply`

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.

## Path parameters

- `messageId` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `body` string — Reply text. Exactly one of `body` and `reaction` is required.
  - `reaction` string — Reaction to send: `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`, or a single emoji. Exactly one of `body` and `reaction` is required.

## Response `201`

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

- MessagesReplyToMessageResponse201
  - `message` Message
    - `id` string
    - `phoneNumberId` string
    - `from` string — Sender in E.164 format.
    - `to` string — Recipient in E.164 format.
    - `body` string
    - `direction` 'inbound' | 'outbound'
    - `channel` 'sms' | 'imessage' | 'rcs' | 'unknown' — The channel the message was delivered on. `sms` for SMS/call numbers. For iMessage numbers, inbound messages report the channel actually used — `imessage`, `rcs`, or `sms`. Outbound iMessage sends report `unknown`, because the iMessage channel does not confirm which channel was ultimately used.
    - `service` 'imessage' | 'rcs' | 'sms' — For iMessage numbers, the confirmed delivery channel. Null for SMS/call numbers (where `channel` already says `sms`). Deprecated — prefer `channel`, which is authoritative.
    - `status` 'sent' | 'delivered' | 'undelivered' | 'failed' | 'unknown' | 'received' — Delivery status. Outbound SMS/call messages start at `sent` and reach a terminal `delivered`, `undelivered`, or `failed`. Outbound iMessage messages are `unknown` (the iMessage channel does not report delivery). Inbound messages are `received`.
    - `statusError` string, nullable — A human-readable reason, present only when `status` is `undelivered` or `failed` (for example, when a carrier rejects the message). Null otherwise.
    - `media` MessageMedia[] — Media attachments on the message, in send order. Empty for plain text messages.
      - `id` string — Public media ID — an unguessable 32-character token.
      - `url` string, uri — Stable public URL serving the media (see Get public media). Safe to use directly as an image source; requires no authentication.
      - `contentType` string — MIME type of the media.
      - `originalUrl` string, nullable — The caller-supplied source URL on outbound messages. Null on inbound messages and when the media was uploaded directly as bytes — inbound media is always served from `url`.
    - `replyToId` string, nullable — ID of the message this one replies or reacts to. Set on messages created via Reply to a message, and on inbound threaded replies and reactions received on iMessage numbers. Null for ordinary messages, or when the target of an inbound reply isn't a message on your account.
    - `reaction` string, nullable — The reaction this message carries — a reaction name (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) or an emoji — when the message is a reaction, sent or received. Null otherwise. A reaction delivered natively has an empty `body`; a reaction delivered as a regular message over SMS carries the emoji in `body` too.
    - `createdAt` string, date-time

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.
- `402` — Insufficient Dial credit. The number is pay-as-you-go and the account's credit balance is at or below zero. Add credit or start a subscription. (error code `insufficient_credit`.)
- `404` — The requested resource was not found on this account.
- `429` — The recipient is rate-limited. New contacts on iMessage numbers can only receive a limited number of messages until they reply; once they respond, the limit lifts. (error code `rate_limited`.)

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/versions/cfa621230237/schema)