Read conversations

Look up contacts, threads, and message history with the Helios API.

The API can read the same contacts and conversations your team sees in the inbox. A common pattern is to pair it with a webhook: the webhook tells you something happened, and the API fills in the details.

Every request uses your API key and only returns data from the key’s inbox.

How conversations are organized

• A contact (customer in the API) is a person, identified by phone number within an inbox.
• A thread is the conversation with one contact. Each contact has a single thread per inbox, shared by texts, emails, and form submissions.
• A message is one text, email, or form submission in a thread, in either direction.

Get the message before a reply

When a contact replies, an incoming_message webhook includes the reply as data.message, with its thread ID. To see what they were replying to, list the thread’s most recent messages, newest first:

curl "https://api.sendhelios.com/v1/messages?thread=THREAD_ID&sort=-createdAt&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Find the reply in the results by its id. The messages after it in the array came before it in the conversation. Match on id rather than position: an auto-reply or another flow message sent after the reply can appear ahead of it.

Look up a contact

Use the webhook’s customer ID to get the contact’s phone number, name, and custom properties:

curl https://api.sendhelios.com/v1/customers/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

To find a contact by phone number instead, filter the list. URL-encode the + as %2B:

curl "https://api.sendhelios.com/v1/customers?phoneNumber=%2B15555550123" \
  -H "Authorization: Bearer YOUR_API_KEY"

List threads

GET /v1/threads returns the inbox’s conversations. It returns read and unread threads unless you pass status, for example status=unread or status=all.

Paging

List endpoints return a JSON array and an x-helios-meta-count header with the total number of matches. Page with limit and offset:

curl -i "https://api.sendhelios.com/v1/threads?limit=100&offset=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort with sort, prefixing the field with - for descending order (sort=-createdAt).

Reply from your system

To text a contact, use Create message. The message appears in the contact’s thread in Helios like any other outgoing message, and contacts who have opted out are skipped.

Browse every endpoint and field in the API reference.