Send conversations through the API

Supported conversations and access

The REST API accepts text transcripts and individual messages from your own chatbot, with the conversation IDs and roles your application supplies.

The API key belongs to one Bubbling source in one project. Keep it in your server configuration.

Before you start

• A Bubbling account with access to your project.
• Access to the application that sends your chatbot transcripts or messages.
• A developer or technical teammate for the integration. The example below needs a terminal with curl.

Create an API key

1. In Bubbling, open Connect. If a source already exists, select New connection.
2. Select REST API.
3. Select Generate key.
4. Copy the key into your application configuration.

Send a transcript

1. Replace YOUR_API_KEY in this request with your key.
2. Run the request from your terminal.

curl https://ingest.bubbling.ai/v1/conversations \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"conversations":[{
    "conversationId":"help-center-example-1",
    "messages":[{
      "messageId":"message-1",
      "role":"visitor",
      "content":"I want to cancel my subscription.",
      "createdAt":"2026-09-17T10:00:00Z"
    }]
  }]}'

Check the result

A successful request returns an accepted count. Open Conversations in the same project to check the transcript.

The accepted count tells you how many conversations Bubbling received. It does not mean that a monitor found a match.

The API also accepts individual messages at /v1/messages. The same conversation and message IDs update existing records without duplicates.

Import behavior and limitations

Your application sends history and new messages. Bubbling does not fetch transcripts from your chatbot automatically.

The API accepts message text. It does not download attachments or transcribe recordings.

An accepted request does not produce an immediate alert. Review runs separately and requires an active monitor that matches the conversation.

Common problems

• For a 401 response, check the key and the Authorization: Bearer header.
• For a 400 response, correct the field named in the error, then resend the batch with the same IDs.
• If conversations appear in the wrong project, use the API key from the project you want to import into.

Create your first alert

1. After a conversation appears in Conversations, open Monitors.
2. Create a monitor and select Lost sale under Common monitors.
3. Select Test on past conversations to check the example against recent conversations.
4. Close the results and check that Active state is on.
5. Select Save.

Receive alerts by email or Slack

1. Open Settings and turn Notifications on.
2. Set Frequency to As it happens or Once a day.
3. Under Email, select Send test message and check the project owner inbox.
4. If Slack is available, connect your workspace and choose a channel.
5. Turn the Slack switch on and send a test message.