API REFERENCE

Request

POST https://useemote.com/v1/react

Headers

HEADER	DESCRIPTION
`Authorization`	Required. `Bearer YOUR_API_KEY`. API keys must remain on the server.
`Content-Type`	Required. `application/json`.
`Idempotency-Key`	Optional. 1–128 printable ASCII characters without spaces. See Usage & retries.

Body

Only message is required. Select a field for its full definition below.

FIELD	TYPE	DESCRIPTION
`message`	string · required	The current user message. 1–4,000 characters.
`agent`	string · optional	The agent’s system prompt or reaction preferences. Up to 12,000 characters.
`context`	array · optional	Up to 12 previous messages, oldest first. Defaults to an empty array.
`reactions`	array · optional	Built-in emojis or custom reaction objects. Up to 254 unique options. Defaults to 12 emojis.
`frequency`	enum · optional	`reserved`, `balanced` (default), or `expressive`.

{
  "message": "We just launched!",
  "agent": "A friendly assistant. Celebrate good news.",
  "context": [
    {
      "role": "user",
      "content": "We’re launching tomorrow."
    },
    {
      "role": "assistant",
      "content": "Good luck with the launch!"
    }
  ],
  "reactions": [
    "❤️",
    "👍",
    "🎉"
  ],
  "frequency": "balanced"
}

The JSON body is limited to 64 KiB. Message, agent, context content and reaction IDs, and reaction options share a 12,000-byte UTF-8 input limit. The encoded inference request has a separate 20,000-byte limit. See Errors & limits.

Parameters

Unknown fields are rejected, including in context and reaction objects. Message text, agent text, context content, and custom reaction descriptions are trimmed before validation.

`message`

string · required

The current user message. 1–4,000 characters after trimming. No default.

{
  "message": "We just launched!"
}

`agent`

string · optional

The agent’s system prompt or a description of its tone and reaction preferences. Up to 12,000 characters after trimming. An empty string is accepted. This field guides reaction selection; it does not execute tools or tasks.

Default: A warm, thoughtful assistant. React naturally and sparingly.

{
  "agent": "A professional assistant. Keep reactions understated."
}

`context`

array of objects · optional · default: []

Up to 12 previous messages, ordered oldest first. Exclude the current message. Each request is independent; Emote does not retain conversation history between requests.

FIELD	TYPE	DESCRIPTION
`role`	string · required	`user` or `assistant`.
`content`	string · required	1–2,000 characters after trimming.
`reaction`	string · optional	The previous reaction, a custom ID, or `none`. 1–64 characters with no whitespace or control characters. It does not need to appear in the current `reactions` list. No default.

{
  "context": [
    {
      "role": "user",
      "content": "We’re launching tomorrow."
    },
    {
      "role": "assistant",
      "content": "Good luck with the launch!"
    }
  ]
}

`reactions`

array of strings or objects · optional

The allowed reaction choices, up to 254 options. Omit this field to use the following defaults:

👍❤️😂🎉😮😢🤔🔥💀🙌👀💯

Strings must be one of these built-in emojis. For any other emoji or custom identifier, use an object with the fields below. Strings and objects can be mixed in the same array.

FIELD	TYPE	DESCRIPTION
`id`	string · required	Case-sensitive, 1–64 characters, with no whitespace or control characters. Must be unique across all options, including emoji strings. `none` is reserved.
`description`	string · required	What the reaction means or when to use it. 1–500 characters after trimming.

{
  "reactions": [
    "❤️",
    {
      "id": "laugh",
      "description": "The Ha ha Tapback for a funny message."
    },
    {
      "id": "🙏",
      "description": "Gratitude or thanks."
    }
  ]
}

Emote returns the selected string or custom ID, never the whole object. In this example, possible results are "❤️", "laugh", "🙏", or "none". Your integration maps the result to its UI or messaging provider.

An empty array returns "none" without inference or usage charges. "none" is always an available result, even when the array is nonempty. See Response.

`frequency`

string enum · optional · default: balanced

VALUE	DESCRIPTION
`reserved`	Favors fewer reactions.
`balanced`	The default reaction frequency.
`expressive`	Favors more reactions when appropriate.

These values guide model behavior; they do not guarantee a reaction percentage or a particular result.

{
  "frequency": "reserved"
}

Data handling

Messages, context, and agent instructions are processed by our external inference provider. Emote does not log message bodies or retain agent text or conversation history. Selected reactions, request identifiers, usage, and timing are stored for accounting and retry protection. See the privacy notice.