# React to a message with an emoji, or remove the reaction

`POST https://api.whatsable.app/v1/messages/{id}/reaction`

Required scope: `messages:send`.

Sets the business's emoji reaction to a message, as the reaction picker does in the inbox. `{ "emoji": "" }` removes it.

> **A reaction needs an open 24-hour window.** Outside it, the call answers `422 session_window_closed`.

A new emoji replaces the business's previous reaction, wherever it was set. A message that was withdrawn, that WhatsApp never accepted, or that WhatsApp has not accepted yet (status `pending`), answers `422 message_not_reactable`.

## Authorization

`Authorization: Bearer <API key>` (HTTP bearer, `bearerAuth`). The key looks like `nfy_live_<32 characters>`. An API key from Settings > API keys, sent as `Authorization: Bearer <key>`.

## Parameters

- `id` (path) string, required. The message id. At most 64 characters.
- `Idempotency-Key` (header) string, optional. Any string up to 255 characters. A repeat with the same key and body answers the stored response; with another body, `409 idempotency_key_reused`. At most 255 characters.

## Request body

`application/json`, required.

- `emoji` string, required. One emoji, such as "👍". It replaces the business's previous reaction to the message. An empty string removes it. At most 64 characters.

## Responses

### 200

The message, with its `business_reaction`.

- `object` `"message"`, required.
- `id` string, required. At most 64 characters.
- `conversation_id` string, required. At most 64 characters.
- `contact_id` string, required. At most 64 characters.
- `number_id` string, required. The business number the message was sent from or received on. At most 64 characters.
- `direction` string, required. One of: `"inbound"`, `"outbound"`.
- `type` string, required. One of: `"text"`, `"template"`, `"image"`, `"video"`, `"audio"`, `"document"`, `"sticker"`, `"buttons"`, `"button_reply"`, `"interactive_reply"`, `"location"`, `"contacts"`, `"unsupported"`. New values may appear within v1.
- `status` string, required. `pending` (Meta did not acknowledge it yet), `sent`, `delivered`, `read` or `failed`. A send answers `sent` or `failed`. One of: `"pending"`, `"sent"`, `"delivered"`, `"read"`, `"failed"`.
- `sent_by` string or null, required. Who sent an outbound message. Null on inbound. One of: `"operator"`, `"api"`, `"bot"`, `"broadcast"`, `"proactive"`, `"whatsapp_app"`. New values may appear within v1.
- `to` object or null, required. The recipient of an outbound message. Null on inbound.
  - `phone` string or null, required.
  - `wa_user_id` string or null, required. The Business-Scoped User ID, when WhatsApp gave one.
  - `username` string or null, required. The WhatsApp username, without `@`, when the person has one.
- `from` object or null, required. The sender of an inbound message. Null on outbound.
  - `phone` string or null, required.
  - `wa_user_id` string or null, required. The Business-Scoped User ID, when WhatsApp gave one.
  - `username` string or null, required. The WhatsApp username, without `@`, when the person has one.
- `text` string or null, required. The text, a caption, or the body of a template or buttons message.
- `template` object or null, required. The template a template message used. Null otherwise.
  - `id` string, required. At most 64 characters.
  - `name` string, required.
  - `language` string, required.
- `media` object or null, required.
  - `id` string, required. The media file id. At most 64 characters.
  - `mime_type` string, required. The file's content type.
  - `size_bytes` integer, required. The stored file size in bytes. 0 when unknown. Minimum 0.
  - `filename` string or null, required. The file name, when WhatsApp or the sender gave one.
  - `url` string or null, required. A signed link that downloads the file without an API key, valid for 15 minutes. Read the message again for a fresh one. Null when the file could not be stored.
  - `transcript` string or null, required. The transcript of an inbound audio message, when one exists. Usually a voice note; an audio file the person attached (`is_voice_note` false) can carry one too, which the inbox does not show. Null otherwise.
- `whatsapp_message_id` string or null, required. Meta's message id (`wamid`) when `transport` is `meta`. A `simulated` send stores an id minted here, starting with `simulated.`. Null when no id was recorded.
- `transport` string, required. `meta` when the send was dispatched to WhatsApp. `simulated` when WhatsAble answered it in this process and did not call WhatsApp. One of: `"meta"`, `"simulated"`.
- `error` object or null, required. Why the message failed. Null unless `status` is `failed`.
  - `code` string, required. `meta_<code>` when WhatsApp refused it with a code, `timeout` when WhatsApp did not answer (it may have gone out), else `send_failed`. New values can appear.
  - `meta_code` integer or null, required. Meta's numeric error code, or null when Meta gave none. Minimum -9007199254740991.
  - `title` string, required.
  - `message` string, required. What happened, in Whatsable's words. Meta's own text is never copied, because it can name the recipient.
  - `how_to_fix` string, required.
  - `source` string, required. Who returned the error: `meta` (WhatsApp) or `whatsable`. One of: `"meta"`, `"whatsable"`.
  - `owner` string, required. Who must act: `caller` (change the request or the account), `whatsable`, or `meta`. One of: `"caller"`, `"whatsable"`, `"meta"`.
  - `retryable` boolean, required. True when a later retry, with a new Idempotency-Key, may succeed.
  - `docs_url` string, required.
  - `fix_url` string or null, optional. Where to fix a payment failure: Meta's payment settings for this WhatsApp Business Account, or the WhatsAble guide that shows the click path when the account id is unknown. Null for every other failure.
  - `support_url` string or null, optional. A mail link to WhatsAble support, with the numeric code and the WhatsApp Business Account id filled in. Set only on a payment failure. Null otherwise. It never names the recipient.
- `created_at` string (date-time), required.
- `delivered_at` string (date-time) or null, required.
- `read_at` string (date-time) or null, required.
- `edited_at` string (date-time) or null, required. When the message was edited after it was sent: by the customer for an inbound message, or from the WhatsApp Business app for an outbound one. `text` holds the current wording.
- `deleted_at` string (date-time) or null, required. When the message was deleted after it was sent: by the customer for an inbound message, or from the WhatsApp Business app for an outbound one. Its text is kept.
- `revisions` array of object, required. The earlier wordings of an edited message, oldest first. Empty when it was never edited.
  - `text` string or null, required. The wording before this edit. Null when that version had no text.
  - `replaced_at` string (date-time), required. When an edit replaced this wording.
- `referral` object or null, required. Meta's Click-to-WhatsApp referral object as Meta sent it, with keys such as `ctwa_clid`. Set only on the inbound message that started a chat from an ad or a post.
- `button_reply` object or null, required.
  - `id` string or null, required. The tapped option: your `buttons` option `id`, a list row id or a template quick reply payload. Null when WhatsApp sent none, or for a tap before this field existed.
  - `title` string, required. The label of the option the person tapped. The same as `text`.
  - `message_id` string or null, required. The `id` of the message that offered the option. Null when WhatsAble did not store that message in this conversation, or WhatsApp did not name it. At most 64 characters.
  - `whatsapp_message_id` string or null, required. Meta's message id (`wamid`) of the message that offered the option. Null when WhatsApp did not name it, or for a tap before this field existed.
- `unverified_figures` array of string, required. Figures in an AI-written message that nothing in the agent's knowledge, files, the customer's own messages or its instructions contains. The message was sent; a person can review them in the inbox. Empty for every other message.
- `figures_checked_at` string (date-time) or null, required. When those figures were marked as checked, in the inbox or through the API; null until then.
- `reply_to` object or null, required. The message this one quotes, as a reply in WhatsApp. Null when it quotes none.
  - `message_id` string or null, required. The `id` of the quoted message. Null when WhatsAble does not hold it in this conversation. At most 64 characters.
- `reactions` array of object, required. The customer's emoji reactions to this message, by their last change, oldest first. Empty when there are none. The business's own reaction is `business_reaction`.
  - `emoji` string, required.
  - `contact_id` string, required. The contact who reacted. At most 64 characters.
  - `created_at` string (date-time), required. When they reacted, or last changed the reaction.
- `business_reaction` object or null, required.
  - `emoji` string, required.
  - `sent_by` string, required. `operator` from the inbox, `api` through the API or an AI app connected to WhatsAble, `whatsapp_app` from the WhatsApp Business app on a phone. One of: `"operator"`, `"api"`, `"whatsapp_app"`. New values may appear within v1.
  - `created_at` string (date-time), required. When the business reacted, or last changed the reaction.
- `forwarded` boolean, required. True when WhatsApp marked the message as forwarded.
- `frequently_forwarded` boolean, required. True when WhatsApp marked it as forwarded many times (shown as "Forwarded many times" in WhatsApp).
- `is_voice_note` boolean or null, required. On an `audio` message: true for a recorded voice note, false for an audio file the person attached. Null on every other type, and on audio when WhatsApp did not say.

### 400

invalid_request: `validation_failed`.

Body: the error body, under "Error body" below.

### 401

authentication: `api_key_in_wrong_place`, `api_key_missing`, `invalid_access_token`, `invalid_api_key`, `legacy_api_key_not_accepted`.

Body: the error body, under "Error body" below.

### 403

permission: `feature_not_in_plan`, `insufficient_scope`, `number_over_plan`, `organization_not_live`, `plan_inactive`.

Body: the error body, under "Error body" below.

### 404

not_found: `message_not_found`.

Body: the error body, under "Error body" below.

### 409

conflict: `idempotency_key_reused`, `idempotency_request_in_progress`.

Body: the error body, under "Error body" below.

### 422

unprocessable: `free_tier_limit`, `message_not_reactable`, `number_not_sending`, `session_window_closed`.

Body: the error body, under "Error body" below.

### 429

rate_limit: `rate_limited`.

Body: the error body, under "Error body" below.

### 500

internal: `internal_error`.

Body: the error body, under "Error body" below.

### 503

unavailable: `service_unavailable`.

Body: the error body, under "Error body" below.

### Error body

Every 4xx and 5xx response above has this body.

- `error` object, required.
  - `type` string, required. The class of the error. Each type has exactly one HTTP status, such as `invalid_request` for 400. One of: `"invalid_request"`, `"authentication"`, `"permission"`, `"not_found"`, `"conflict"`, `"precondition_failed"`, `"unprocessable"`, `"rate_limit"`, `"internal"`, `"unavailable"`.
  - `code` string, required. The stable code a program branches on. Open: new codes are added under an existing status. One of: `"validation_failed"`, `"invalid_address"`, `"template_variable_missing"`, `"invalid_cursor"`, `"from_conflicts_with_conversation"`, `"media_too_large"`, `"media_type_unsupported"`, `"api_key_missing"`, `"invalid_api_key"`, `"api_key_in_wrong_place"`, `"legacy_api_key_not_accepted"`, `"invalid_access_token"`, `"insufficient_scope"`, `"number_not_allowed_for_key"`, `"plan_inactive"`, `"feature_not_in_plan"`, `"organization_not_live"`, `"number_over_plan"`, `"number_not_found"`, `"template_not_found"`, `"contact_not_found"`, `"conversation_not_found"`, `"message_not_found"`, `"label_not_found"`, `"media_not_found"`, `"route_not_found"`, `"scheduled_message_not_found"`, `"broadcast_not_found"`, `"ai_bot_not_found"`, `"knowledge_file_not_found"`, `"ai_bot_file_not_found"`, `"conversation_note_not_found"`, `"idempotency_key_reused"`, `"idempotency_request_in_progress"`, `"template_name_conflict"`, `"template_waba_not_connected"`, `"template_used_by_broadcast"`, `"label_name_conflict"`, `"ai_bot_name_conflict"`, `"precondition_failed"`, `"session_window_closed"`, `"template_not_approved"`, `"template_wrong_waba"`, `"template_not_supported"`, `"template_rejected_by_meta"`, `"number_not_sending"`, `"contact_has_no_address"`, `"label_limit_reached"`, `"free_tier_limit"`, `"ai_bot_limit_reached"`, `"scheduled_message_not_pending"`, `"broadcast_not_cancellable"`, `"broadcast_not_pausable"`, `"broadcast_not_resumable"`, `"ai_bot_not_archived"`, `"ai_bot_archived"`, `"ai_bot_file_limit_reached"`, `"ai_bot_text_too_long"`, `"label_not_available_on_number"`, `"reply_target_not_quotable"`, `"message_has_no_figures"`, `"message_not_reactable"`, `"rate_limited"`, `"internal_error"`, `"service_unavailable"`. New values may appear within v1.
  - `title` string, required. A short summary for a person. Wording may change.
  - `message` string, required. What happened, for a person. Wording may change.
  - `how_to_fix` string, required. What to change so the request succeeds.
  - `param` string or null, required. The offending field in dotted path form (`template.variables.2`), or null.
  - `source` string, required. Who returned the error: `meta` (WhatsApp) or `whatsable`. One of: `"meta"`, `"whatsable"`.
  - `owner` string, required. Who must act: `caller` (change the request or the account), `whatsable`, or `meta`. One of: `"caller"`, `"whatsable"`, `"meta"`.
  - `retryable` boolean, required. Whether the same request may succeed later without a change.
  - `docs_url` string, required. The docs page for this code.
  - `details` object, required. Structured facts for this code, such as `required_scope` or `meta_code`. Empty when there are none.
  - `request_id` string, required. The `X-Request-Id` of this response. Quote it to support.
  - `plans_url` string, optional. The public page that explains the plans and their limits. Present only on `plan_inactive`, `feature_not_in_plan`, `free_tier_limit` and `number_over_plan`.

## Example request

```bash
curl -X POST 'https://api.whatsable.app/v1/messages/{id}/reaction' \
  -H 'Authorization: Bearer <API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "emoji": "👍"
}'
```
