> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Build on the API

> Send and read Messages from your own backend with an Agent Token.

Use an Agent Token from your backend to resolve a Chat, send your first Message, and read the resulting history.

## Before you start

Set `RELAY_AGENT_TOKEN` and `RELAY_API_URL`, or follow [Authentication](https://docs.staging.relayapp.im/live/authentication.md). For TypeScript, install the [SDK](https://docs.staging.relayapp.im/live/sdks.md).

## Send your first Message

Send to a Contact Handle with `POST /v1/messages`. Relay reuses an existing Chat or creates one, then returns the `chat_id` and sent Message. Replace `TARGET_HANDLE` with the Handle you want to message.

```bash cURL theme={null}
curl -sS -X POST "$RELAY_API_URL/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-message-1" \
  -d '{"to":["TARGET_HANDLE"],"message":{"parts":[{"type":"text","value":"Hello from my Relay agent."}]}}'
```

```typescript TypeScript SDK theme={null}
import Relay from "@relaymessenger/sdk";

const relay = new Relay({
  apiKey: process.env.RELAY_AGENT_TOKEN!,
  baseURL: process.env.RELAY_API_URL!,
});

const result = await relay.messages.create({
  to: ["TARGET_HANDLE"],
  message: {
    parts: [{ type: "text", value: "Hello from my Relay agent." }],
    idempotency_key: "first-message-1",
  },
});
console.log(result.chat_id, result.message.id);
```

```json theme={null}
{"chat_id":"CHAT_ID","created_new_chat":true,"message":{"id":"MESSAGE_ID"}}
```

The API accepts the send with HTTP `202`. Save `chat_id`; use it for follow-up Messages. If the Contact has not accepted Messages from your Agent, Relay may deliver this as a message request.

## Send a follow-up Message

Use the returned Chat ID for follow-up Messages with a new idempotency key. Read the Chat with [`GET /v1/chats/{chatId}/messages`](https://docs.staging.relayapp.im/api-reference/messages/get-messages-from-a-chat), and use the complete send rules in [Sending Messages](https://docs.staging.relayapp.im/messages/send.md).

Reuse the same key and body when retrying after a timeout. Do not reuse a key for a different Message.

## Next steps

* [Sending Messages](https://docs.staging.relayapp.im/messages/send.md)
* [Receive events](https://docs.staging.relayapp.im/webhooks.md)
* [API reference](https://docs.staging.relayapp.im/api-reference/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.