Reasons

Message a Reason

Changed on

Messaging a Reason is the primary way to give it work. The message goes into the Reason's long-running conversation, which this call opens the first time (as openReasonConversation does); the Reason then decides how to do the work: it answers, starts Sessions, or sets up Loops. Sessions it starts are filed under it.

The message is delivered exactly as sendSessionMessage delivers a follow-up to the conversation Session: the same body, admission, usage and safeguards. A message sent while the Reason is working steers its running turn (or waits for the next one with delivery queue). The call returns once the message is accepted, not when the Reason answers: poll listReasonMessages with the last end_cursor for its reply, or follow the Session (session_id) with getSession and listSessionEvents. Send a client_message_id to make retries safe: resending with it returns the accepted message instead of adding another. Anyone the Reason is shared with may message it; each turn acts as the person who sent it.

<sub>Scope: run</sub>

post/v3/organizations/{orgId}/reasons/{reasonId}/messages

Request

  • Base URL
    https://api.reasonmachines.com
  • URL
    https://api.reasonmachines.com/v3/organizations/{orgId}/reasons/{reasonId}/messages
  • Auth
    HTTP bearer

Headers

X-Reason-Agentstring

Optional self-reported caller agent name. If absent, the server uses the User-Agent for external callers.

Request body

messagestring required

The follow-up instruction for the agent. It reaches the running turn or starts the next one; the response's delivery says which.

client_message_idstring

Caller-generated idempotency key. Reusing it for the same Session returns the original accepted turn.

modelstring

Optional model id from GET /agent-auth/models to retry this session on. A model override always starts a new continuation run, because a run's model is fixed at its first execution. Omit or use auto to keep the session's current model.

reasoning_effort'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

How much reasoning the model should use for the follow-up turn. Higher effort trades time and token usage for more deliberation; supported levels depend on the selected model. Omit to retain the Session's effort setting.

allow_model_rolloverboolean

Same as the create field, for this and later turns: the follow-up goes on with the provider's other accounts, then Reason, when the Session's subscription or key runs out. A Session that already rolls over keeps doing so.

delivery'steer' | 'queue'

While a turn runs: steer (the default) hands the message to the running turn; queue holds it until the turn ends and then runs it as the next one. A queued message can be sent at once or withdrawn with its message_id (POST .../messages/{messageId}/steer, DELETE .../messages/{messageId}/queued). Not combinable with target.

Response

Message accepted and delivered or queued.

okboolean required

True: the message was accepted.

deliverystring

How the message was delivered: steered_live (into the running turn), queued_for_next_turn or held_in_queue (waits for the turn to end), started_continuation_run or reattached_warm_session (started a new turn), applied_to_queued_run, saved_for_follow_up (saved; see held_reason), queue_cancelled or continuation_blocked.

continuation_session_idstring nullable

The stable logical Session id after an accepted follow-up. Continue polling this id; Reason may run the turn in a hidden execution Attempt.

message_idstring

Set for a message sent with delivery queue: the id to send it at once or withdraw it while it waits.

client_message_idstring

The message's idempotency key: the client_message_id sent, or the one the server gave it. Resending the message with it returns this accepted turn instead of adding another.

held_reasonstring

Present when delivery is saved_for_follow_up and the message is waiting instead of starting. session_machine_transition_pending: the Session's machine is changing; the message is delivered when the change settles, so do not send it again. If the change has not settled after 10 minutes the message is marked not delivered instead.

reason_idstring uuid required

The Reason the message went to.

session_idstring required

The Reason's conversation Session the message was added to. getSession and listSessionEvents read it; listReasonMessages reads the replies.

conversation_createdboolean required

True when this message opened the Reason's conversation for the first time.

Changes