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 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.

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.

Use an internal staff conversation for testing, not one with a patient.

List your conversations

cURL

Request


curl https://api.bloomtext.com/v1/conversations \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

JavaScript

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

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

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

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.

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.

cURL

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 👋"}'

JavaScript

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

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

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

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, and the message shows up in BloomText under your app user’s name.

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 Understand scopes Browse the API