# Quickstart

> Make your first BloomText API request and send a message in five minutes.

Source: https://www.bloomtext.com/developers/api/quickstart/

This guide takes you from an API key to a message in a real BloomText conversation. You'll list the conversations your app user can see, then post into one.

### Get an API key

API keys are issued to organizations with a signed BAA. [Request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access) if you don't have one yet. Once your organization is enabled, an admin creates an app user for your integration and gives you its key.

Store the key in an environment variable. Never commit it or ship it to a browser.

```bash filename="Terminal"
export BLOOMTEXT_API_KEY="bt_live_4f7c2a9e1b..."
```

### Add your app user to a conversation

In BloomText, open the conversation you want to test with and add your app user as a participant, like you'd add a colleague. The API only returns conversations your app user belongs to.

> **Note:** Use an internal staff conversation for testing, not one with a patient.

### List your conversations

```bash filename="Request"
curl https://api.bloomtext.com/v1/conversations \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"
```

```js filename="list-conversations.mjs"
const response = await fetch('https://api.bloomtext.com/v1/conversations', {
  headers: { Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}` },
})
const { data } = await response.json()
console.log(data)
```

```python filename="list_conversations.py"
import os

import requests

response = requests.get(
    "https://api.bloomtext.com/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}"},
)
response.raise_for_status()
print(response.json()["data"])
```

```go filename="main.go"
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.bloomtext.com/v1/conversations", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
```

```ruby filename="list_conversations.rb"
require "net/http"
require "json"

uri = URI("https://api.bloomtext.com/v1/conversations")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)["data"]
```

The response lists every conversation your app user is in. Copy the `id` of your test conversation.

```json filename="Response · 200 OK"
{
  "data": [
    {
      "id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0",
      "organization_id": "6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c",
      "type": "group",
      "created_at": "2026-09-14T16:02:11Z"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}
```

### Send a message

Post a message into that conversation. The `Idempotency-Key` header makes the request safe to retry. See [Idempotency](https://www.bloomtext.com/developers/api/idempotency/).

```bash filename="Request"
curl -X POST https://api.bloomtext.com/v1/conversations/e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0/messages \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello from the BloomText API 👋"}'
```

```js filename="send-message.mjs"
const conversationId = 'e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0'

const response = await fetch(`https://api.bloomtext.com/v1/conversations/${conversationId}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ body: 'Hello from the BloomText API 👋' }),
})
console.log(await response.json())
```

```python filename="send_message.py"
import os
import uuid

import requests

conversation_id = "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0"

response = requests.post(
    f"https://api.bloomtext.com/v1/conversations/{conversation_id}/messages",
    headers={
        "Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"body": "Hello from the BloomText API 👋"},
)
response.raise_for_status()
print(response.json())
```

```go filename="main.go"
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"

	"github.com/google/uuid"
)

func main() {
	conversationID := "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0"
	url := "https://api.bloomtext.com/v1/conversations/" + conversationID + "/messages"
	body := bytes.NewBufferString(`{"body":"Hello from the BloomText API 👋"}`)

	req, _ := http.NewRequest("POST", url, body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
	req.Header.Set("Idempotency-Key", uuid.NewString())
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}
```

```ruby filename="send_message.rb"
require "net/http"
require "json"
require "securerandom"

conversation_id = "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0"
uri = URI("https://api.bloomtext.com/v1/conversations/#{conversation_id}/messages")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
request["Idempotency-Key"] = SecureRandom.uuid
request["Content-Type"] = "application/json"
request.body = { body: "Hello from the BloomText API 👋" }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)
```

You get back the new [Message object](https://www.bloomtext.com/developers/api/reference/message-object/), and the message shows up in BloomText under your app user's name.

```json filename="Response · 201 Created"
{
  "id": "4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1",
  "conversation_id": "e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0",
  "sender_id": "8b9c2d2f-6b1a-44f4-a7b1-0d6d3f2d6f55",
  "created_at": "2026-09-21T15:04:05Z",
  "type": "text",
  "body": "Hello from the BloomText API 👋",
  "file": null,
  "reply_to_message_id": null
}
```

## Next steps

  - [Listen with webhooks](https://www.bloomtext.com/developers/api/webhooks/)
  - [Understand scopes](https://www.bloomtext.com/developers/api/authentication/)
  - [Browse the API](https://www.bloomtext.com/developers/api/reference/)