Messages

Send messages to users and receive their replies

Messages are only available for interactive agents. Approval-only agents cannot send or receive messages — the API returns 403.

POST/api/agent/events

Send a chat message from your agent. The message appears instantly in the user's Nod app.

typerequired

string

Must be "message"

text

string

Message body (supports markdown). Required unless image_base64 is provided.

image_base64

string

Base64-encoded image (with or without data URI prefix). Uploaded to storage, delivered as a public URL.

conversation_id

string

Target conversation. Auto-created if omitted.

Text message

POST /api/agent/events
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "type": "message",
  "text": "Deployment complete. All checks passed."
}

Message with image

{
  "type": "message",
  "text": "Here's the build output:",
  "image_base64": "data:image/png;base64,iVBORw0KGgo..."
}

Response

{
  "status": "ok",
  "message_id": "msg_xyz789"
}

POSTWebSocket frame

Agents with a persistent WebSocket send messages as JSON frames.

typerequired

string

Must be "message"

text

string

Message body (markdown)

conversation_id

string

Target conversation

image_base64

string

Base64-encoded image (max ~5MB). Uploaded to storage automatically.

report_title

string

Renders message as a tappable report card

report_description

string

Subtitle on the card

task_run_id

string

Associate with a task run

Chat message

{
  "type": "message",
  "text": "Build succeeded. Deploying now...",
  "conversation_id": "conv_abc123"
}

Report (tappable card)

{
  "type": "message",
  "text": "# Daily Summary\n\n- Deploys: 3\n- Errors: 0",
  "report_title": "Daily Summary",
  "report_description": "Deploys and errors for today",
  "conversation_id": "conv_abc123"
}

Task result

{
  "type": "message",
  "text": "Backup completed. 2.4 GB total.",
  "task_run_id": "run_abc123"
}

Image message

{
  "type": "message",
  "text": "Screenshot of the error:",
  "image_base64": "data:image/png;base64,iVBORw0KGgo..."
}

Receiving messages

When a user sends a message from the Nod app, your agent receives a user_message event via WebSocket or webhook. Users can send text, images, multiple images, and voice messages — all delivered in the same event format.

GETuser_message event

Delivered via WebSocket if online, otherwise POSTed to your webhook_url.

text

string

Message text (for voice messages, contains the transcription)

sender_name

string

Display name of the user

conversation_id

string

Conversation this message belongs to

message_id

string

Unique message identifier

image_url

string | null

Public URL to a single image

image_urls

string[] | null

Public URLs to multiple images

audio_url

string | null

Public URL to the original voice recording (m4a). The text field already contains the transcription.

Text message

{
  "type": "user_message",
  "text": "Deploy the latest build to staging.",
  "sender_name": "Alice",
  "conversation_id": "conv_abc123",
  "message_id": "msg_001"
}

Single image

{
  "type": "user_message",
  "text": "What's wrong with this error?",
  "sender_name": "Alice",
  "conversation_id": "conv_abc123",
  "message_id": "msg_002",
  "image_url": "https://storage.asknod.ai/media/1720000000.png"
}

Multiple images

{
  "type": "user_message",
  "text": "Compare these designs",
  "sender_name": "Alice",
  "conversation_id": "conv_abc123",
  "message_id": "msg_003",
  "image_urls": [
    "https://storage.asknod.ai/media/design-a.png",
    "https://storage.asknod.ai/media/design-b.png"
  ]
}

Voice message (pre-transcribed)

{
  "type": "user_message",
  "text": "Deploy the latest build to staging",
  "sender_name": "Alice",
  "conversation_id": "conv_abc123",
  "message_id": "msg_004",
  "audio_url": "https://storage.asknod.ai/media/1720000001.m4a"
}

GET/api/agent/conversations/{conversation_id}/messages

Fetch message history for a conversation. Returns messages in reverse chronological order (newest first). Use this to build context for your agent so it can reference prior messages.

conversation_idrequired

string

The conversation to fetch messages from (path parameter)

limit

integer

Number of messages to return (1-100, default 50)

cursor

string

ISO timestamp for pagination. Returns messages older than this timestamp.

Request

GET /api/agent/conversations/conv_abc123/messages?limit=20
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

Response

[
  {
    "id": "msg_002",
    "conversation_id": "conv_abc123",
    "sender": "agent",
    "sender_name": "My Agent",
    "text": "Here are the latest results...",
    "created_at": "2025-03-25T12:01:00Z"
  },
  {
    "id": "msg_001",
    "conversation_id": "conv_abc123",
    "sender": "human",
    "sender_name": "Alice",
    "text": "Look up the latest news",
    "created_at": "2025-03-25T12:00:00Z"
  }
]

Media URLs

Image and audio URLs are publicly accessible — no authentication needed to download them. Your agent can fetch them directly with a simple HTTP GET.

Voice messages are pre-transcribed

Voice messages are transcribed on the user's device before being sent to your agent. The text field contains the transcription, and audio_url contains the original recording. Your agent just reads text — no speech-to-text integration needed.

Users configure their transcription provider (OpenAI Whisper or Deepgram) and API key in the Nod app settings. Keys are stored securely on the device using the OS keychain and are never sent to Nod servers.

How to handle media

Nod delivers the URLs. What you do with them is up to your integration:

Images — download and pass to a vision model, save locally, or ignore
Voice messages — just read the text field (already transcribed). The audio_url is available if you need the original recording.
Text only — just read the text field and skip media fields