> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations Overview

> Create, list, update, delete, and manage conversations and messages across SMS, email, WhatsApp, and live chat using the HoopAI Platform Conversations REST API.

The Conversations API gives programmatic access to the messaging layer of the HoopAI Platform. Use it to create conversations, send outbound messages across SMS, email, WhatsApp, Facebook, Instagram, and live chat channels, retrieve full message history, handle inbound message ingestion, upload file attachments, cancel scheduled messages, and retrieve call recordings and transcriptions. It supports both automation-driven messaging and real-time live chat integrations.

## Base URL

```
https://services.leadconnectorhq.com
```

## Authentication

All endpoints require a Bearer token and an API version header.

```bash theme={null}
Authorization: Bearer <access_token>
Version: 2021-07-28
```

See [OAuth 2.0](/api-reference/oauth/overview) to obtain an access token.

## OAuth scopes

| Scope                            | Access                                   |
| -------------------------------- | ---------------------------------------- |
| `conversations.readonly`         | Read conversations                       |
| `conversations.write`            | Create, update, and delete conversations |
| `conversations/message.readonly` | Read messages within conversations       |
| `conversations/message.write`    | Send messages and upload attachments     |
| `conversations/livechat.write`   | Send live chat typing indicators         |

## Quick start

Send a new outbound SMS message:

```bash theme={null}
curl -X POST https://services.leadconnectorhq.com/conversations/messages \
  -H "Authorization: Bearer <access_token>" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "conversationId": "ABCHkzuJQ8ZMd4Te84GK",
    "message": "Hello, your appointment is confirmed for tomorrow at 10am."
  }'
```

## Endpoints

| Method   | Path                                                                                | Description                          |
| -------- | ----------------------------------------------------------------------------------- | ------------------------------------ |
| `POST`   | `/conversations/`                                                                   | Create conversation                  |
| `GET`    | `/conversations/search`                                                             | Search conversations                 |
| `GET`    | `/conversations/{conversationId}`                                                   | Get conversation                     |
| `PUT`    | `/conversations/{conversationId}`                                                   | Update conversation                  |
| `DELETE` | `/conversations/{conversationId}`                                                   | Delete conversation                  |
| `GET`    | `/conversations/{conversationId}/messages`                                          | Get messages by conversation ID      |
| `POST`   | `/conversations/messages`                                                           | Send a new message                   |
| `POST`   | `/conversations/messages/inbound`                                                   | Add an inbound message               |
| `POST`   | `/conversations/messages/outbound`                                                  | Add an external outbound call        |
| `POST`   | `/conversations/messages/upload`                                                    | Upload file attachments              |
| `GET`    | `/conversations/messages/{id}`                                                      | Get message by message ID            |
| `PUT`    | `/conversations/messages/{messageId}/status`                                        | Update message status                |
| `DELETE` | `/conversations/messages/{messageId}/schedule`                                      | Cancel a scheduled message           |
| `GET`    | `/conversations/messages/email/{id}`                                                | Get email by ID                      |
| `DELETE` | `/conversations/messages/email/{emailMessageId}/schedule`                           | Cancel a scheduled email message     |
| `GET`    | `/conversations/messages/{messageId}/locations/{locationId}/recording`              | Get recording by message ID          |
| `GET`    | `/conversations/locations/{locationId}/messages/{messageId}/transcription`          | Get transcription by message ID      |
| `GET`    | `/conversations/locations/{locationId}/messages/{messageId}/transcription/download` | Download transcription by message ID |
| `POST`   | `/conversations/providers/live-chat/typing`                                         | Send live chat typing indicator      |

## Related

* [Contacts API](/api-reference/contacts/overview) — Retrieve the contact associated with a conversation
* [Calendars API](/api-reference/calendars/overview) — Book appointments and send confirmation messages
* [Workflows API](/api-reference/workflows/overview) — Trigger automated messaging sequences