Chats - Blujay API

A chat is one conversation between one of your Blujay phone numbers and one or more people. A chat with one person is direct; a chat with two or more is a group.

Create a chat

You create a chat by sending its first message with POST /v1/chats. See Sending Messages.

List chats

curl "https://api.blujay.io/v1/chats?limit=25" \
  -H "Authorization: Bearer blu_your_api_key"

const response = await fetch("https://api.blujay.io/v1/chats?limit=25", {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.data.map((chat) => chat.chat_id), data.has_more);

import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    params={"limit": 25},
    timeout=60,
)
data = response.json()["data"]
print([chat["chat_id"] for chat in data["data"]], data["has_more"])

Chats come back most recently active first. Pass next_cursor as cursor for the next page. See Pagination.

Find a person’s chats

Add to to list only the chats a person is in, direct and group, by their phone number or email address. Add from to keep only the chats on one of your numbers. Together they find the direct chat between your number and that person:

curl -G https://api.blujay.io/v1/chats \
  --data-urlencode "to=+15555550123" \
  --data-urlencode "from=+15555550100" \
  -H "Authorization: Bearer blu_your_api_key"

const params = new URLSearchParams({ to: "+15555550123", from: "+15555550100" });
const response = await fetch(`https://api.blujay.io/v1/chats?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.data.find((chat) => chat.type === "direct")?.chat_id);

import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    params={"to": "+15555550123", "from": "+15555550100"},
    timeout=60,
)
chats = response.json()["data"]["data"]
print(next((chat["chat_id"] for chat in chats if chat["type"] == "direct"), None))

to takes a US phone number, in E.164 or US format, or an email address. Groups the person has left aren’t included.
Passing one of your own numbers in to returns 400 VALIDATION_ERROR; use from for that.
A from number that isn’t in your workspace returns an empty list.

Retrieve a chat

curl https://api.blujay.io/v1/chats/chat_abc123 \
  -H "Authorization: Bearer blu_your_api_key"

const response = await fetch("https://api.blujay.io/v1/chats/chat_abc123", {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.type, data.service, data.participants);

import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats/chat_abc123",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    timeout=60,
)
data = response.json()["data"]
print(data["type"], data["service"], data["participants"])

Field	What it tells you
`type`	`direct` or `group`
`participants`	The people in the chat, with their `contact_id`
`phone_number_id`	Which of your numbers the chat uses
`service`	`iMessage`, `RCS` or `SMS`, once Blujay has confirmed it

Read a chat’s messages

GET /v1/chats/{chat_id}/messages returns the messages in one chat. See Sending Messages.

Mark a chat as read

POST /v1/chats/{chat_id}/read marks the chat read and, in direct iMessage and RCS chats, sends a read receipt. See Typing and Read Receipts.

Group Chats

Start a group, change its name and photo, and manage who’s in it.

Number Lookup

Check whether a number uses iMessage before you text it.

Typing and Read Receipts

Show typing and mark chats as read.

Name and Photo Sharing

Share your number’s name and photo with the people you text.

​Create a chat

​List chats

​Find a person’s chats

​Retrieve a chat

​Read a chat’s messages

​Mark a chat as read

​Related