Messaging

`send_message`

Sends text or media to a conversation. Messaging an IDLE thread resumes triage on that thread.

Parameter	Type	Details
`conversationId`	string	Required conversation ID
`region`	string	Optional ISO 3166-2 code when the patient has moved; applies to the next request, not one in flight
`messages`	array of strings	First-person patient messages; multiple entries are sent together
`lastSeenMessageId`	string	Latest message ID already read; confirms the conversation is current
`waitForReply`	boolean	Defaults to `true`; use `false` for fire-and-forget
`maxWaitSeconds`	number	Optional wait duration when `waitForReply` is true
`media`	object	Optional photo or video: `type`, `contentType`, and `data` (base64) or public HTTPS `url`
`idempotencyKey`	string	Available on agent hosts for retry safety

Read the conversation first with get_conversation or wait_for_reply, or pass its latest lastSeenMessageId. A stale ID returns the current conversation state with READ_REQUIRED; review it before retrying. By default, the call sends the message and waits for the next reply. The wait resolves on a triage reply, provider connection, or provider message. If it returns stillWaiting, continue with wait_for_reply; do not send the same message again. Set waitForReply: false when you will await the result separately with wait_for_reply. When the patient moves, pass their current region in region. It applies to the next provider request, not a request already in flight. At PAYMENT_REQUIRED, the send is refused and the result carries the payment gate. Relay its summary and offer paymentGate.paymentUrl. On the Stripe page the patient approves a temporary hold; it is captured only if a doctor joins and released otherwise. No card setup is required. Results can include sent, messagesSent, mediaSent, reply or replies, stillWaiting, paymentRequired, paymentGate, and nextStep. A media upload fallback can include uploadUrl, uploadRef, messageId, mediaType, contentType, expiresIn, and instructions.

Example response

{
    "sent": true,
    "messagesSent": 2,
    "conversationId": "conversation_example",
    "conversationActive": true,
    "status": "TRIAGING",
    "userMessage": "Your message has been sent.",
    "agentInstructions": ["Call wait_for_reply with this conversationId to await a response."],
    "nextStep": "wait_for_reply",
    "nextStepArgs": {
        "conversationId": "conversation_example"
    }
}

Safe retries

Agent hosts advertise idempotencyKey for send_message, start_conversation, create_care_job, and respond_to_care_job. The same key can also be supplied as _meta["arlo.health/idempotencyKey"]. Reusing a key returns the original result for that action rather than applying it twice.

`get_media_url`

Supply conversationId, messageId, and mediaType (photo, video, or file) from a conversation message. For a file, also pass fileName. Photos are returned inline as an image, with a signed URL as a fallback. Videos are returned as signed URLs. PDFs are rasterized into up to 10 page images; other files are returned as signed URLs. Signed URLs typically expire after one hour.

Overview

Tools Reference

`send_message`

Example response

Safe retries

`get_media_url`

​send_message

​Example response

​Safe retries

​get_media_url

`send_message`

Example response

Safe retries

`get_media_url`