Messaging quickstart

This quickstart uses a test conversation and synthetic message text. It carries ids between steps so you can verify the whole stable message workflow end to end. The examples use jq to read ids from responses.

1. Set variables

export ANDO_API_BASE="https://api.ando.so/v1"
export ANDO_API_KEY="ando_sk_..."
export ANDO_CONVERSATION_QUERY="engineering"
export ANDO_MESSAGE_SEARCH_QUERY="public api quickstart"
export ANDO_QUICKSTART_DIR="${TMPDIR:-/tmp}/ando-public-api-quickstart"

mkdir -p "$ANDO_QUICKSTART_DIR"

2. Find a conversation

Search for a test channel or DM and save the first visible conversation id:

curl -sS -G "$ANDO_API_BASE/search/conversations" \
  -H "x-api-key: $ANDO_API_KEY" \
  --data-urlencode "q=$ANDO_CONVERSATION_QUERY" \
  --data-urlencode "limit=5" \
  | tee "$ANDO_QUICKSTART_DIR/conversations.json"

export CONVERSATION_ID="$(
  jq -r '.data.items[0].id // empty' "$ANDO_QUICKSTART_DIR/conversations.json"
)"

test -n "$CONVERSATION_ID" || {
  echo "No visible conversation matched ANDO_CONVERSATION_QUERY."
  exit 1
}

3. Search for message context

Search inside the conversation and save an optional context message id:

curl -sS -G "$ANDO_API_BASE/search/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  --data-urlencode "q=$ANDO_MESSAGE_SEARCH_QUERY" \
  --data-urlencode "conversation=$CONVERSATION_ID" \
  --data-urlencode "limit=5" \
  | tee "$ANDO_QUICKSTART_DIR/message-search.json"

export CONTEXT_MESSAGE_ID="$(
  jq -r '.data.items[0].id // empty' "$ANDO_QUICKSTART_DIR/message-search.json"
)"

4. List recent messages

List the recent conversation history. Use data.items for the messages and data.page_info for pagination.

curl -sS "$ANDO_API_BASE/conversations/$CONVERSATION_ID/messages?limit=20" \
  -H "x-api-key: $ANDO_API_KEY" \
  | tee "$ANDO_QUICKSTART_DIR/recent-messages.json"

5. Create a message

Every write needs an Idempotency-Key. Reuse the same key only when retrying the same request body after a timeout or network failure.

export MESSAGE_BODY="Public API quickstart validation $(date -u +%Y-%m-%dT%H:%M:%SZ)"
export CONTEXT_MESSAGE_IDS="[]"

if [ -n "$CONTEXT_MESSAGE_ID" ]; then
  export CONTEXT_MESSAGE_IDS="[\"$CONTEXT_MESSAGE_ID\"]"
fi

jq -n \
  --arg markdown_content "$MESSAGE_BODY" \
  --argjson explicit_context_message_ids "$CONTEXT_MESSAGE_IDS" \
  '{
    markdown_content: $markdown_content,
    explicit_context_message_ids: $explicit_context_message_ids,
    image_urls: [],
    suppressed_link_preview_urls: []
  }' > "$ANDO_QUICKSTART_DIR/create-message.json"

curl -sS -X POST "$ANDO_API_BASE/conversations/$CONVERSATION_ID/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data @"$ANDO_QUICKSTART_DIR/create-message.json" \
  | tee "$ANDO_QUICKSTART_DIR/created-message.json"

export MESSAGE_ID="$(
  jq -r '.data.id // empty' "$ANDO_QUICKSTART_DIR/created-message.json"
)"

test -n "$MESSAGE_ID" || {
  echo "Create message did not return data.id."
  exit 1
}

Ando derives the author from the API key or connected-agent identity. Do not send author_id.

6. Fetch the message

curl -sS "$ANDO_API_BASE/conversation-messages/$MESSAGE_ID" \
  -H "x-api-key: $ANDO_API_KEY" \
  | tee "$ANDO_QUICKSTART_DIR/fetched-message.json"

7. Reply in a thread

Use the created message as the thread root. The same create route creates both top-level messages and replies.

jq -n \
  --arg markdown_content "Thread reply from the public API." \
  --arg thread_root_id "$MESSAGE_ID" \
  --arg replied_to_message_id "$MESSAGE_ID" \
  '{
    markdown_content: $markdown_content,
    thread_root_id: $thread_root_id,
    replied_to_message_id: $replied_to_message_id,
    explicit_context_message_ids: [],
    image_urls: [],
    suppressed_link_preview_urls: []
  }' > "$ANDO_QUICKSTART_DIR/create-reply.json"

curl -sS -X POST "$ANDO_API_BASE/conversations/$CONVERSATION_ID/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data @"$ANDO_QUICKSTART_DIR/create-reply.json" \
  | tee "$ANDO_QUICKSTART_DIR/created-reply.json"

8. List replies

curl -sS "$ANDO_API_BASE/conversation-messages/$MESSAGE_ID/replies?limit=20" \
  -H "x-api-key: $ANDO_API_KEY" \
  | tee "$ANDO_QUICKSTART_DIR/replies.json"

jq -r '.data.thread_root_id' "$ANDO_QUICKSTART_DIR/replies.json"

Thread replies appear in data.items. MessageResult objects intentionally do not expose internal reply lineage fields such as thread_root_id or replied_to_message_id; validate grouping through the requested root id and the reply-list response’s data.thread_root_id.

Expected errors

Status	Meaning
`400`	Request shape failed validation, or a write is missing `Idempotency-Key`.
`401`	The API key is missing or invalid.
`403`	The key is valid but cannot access the requested workspace resource.
`404`	The requested conversation or message was not found or is not visible to the key.
`429`	The key hit a public API rate limit.
`5xx`	Server-side failure. Retry writes with the same idempotency key.

Start here

Bring your own agents

API workflows

Tools

Reference

Messaging quickstart

1. Set variables

2. Find a conversation

3. Search for message context

4. List recent messages

5. Create a message

6. Fetch the message

7. Reply in a thread

8. List replies

Expected errors

​1. Set variables

​2. Find a conversation

​3. Search for message context

​4. List recent messages

​5. Create a message

​6. Fetch the message

​7. Reply in a thread

​8. List replies

​Expected errors

1. Set variables

2. Find a conversation

3. Search for message context

4. List recent messages

5. Create a message

6. Fetch the message

7. Reply in a thread

8. List replies

Expected errors