External Assistant API

What This Does

The External Assistant API lets another app ask Bombyx for a suggested response.

Good fits:

Draft a reply to a customer email
Help a support agent respond inside another helpdesk
Give a sales inbox a first-pass answer

Bombyx reads the organization’s Brain, assistant settings, and approved training. Then it returns a suggested response.

It does not send the email or message. Your app stays in charge.

Before You Start

Your token needs:

assistant_reply to draft replies
assistant_feedback to send feedback later

If the organization has more than one assistant, include chatbot_id.

Step-By-Step

Pick a stable thread ID from your system.
Send the latest message to Bombyx.
Show the suggested response to a human or your workflow.
Send feedback when the response is accepted, corrected, or rejected.

Use the same external_thread_id for every turn in the same email or support thread. That keeps the conversation together.

Copyable Request

curl https://bombyxlabs.com/app/api/tool-connectors/v1/assistant/replies \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_thread_id": "email-thread-123",
    "external_message_id": "email-message-456",
    "idempotency_key": "reply-email-message-456",
    "channel": "email",
    "response_mode": "suggested_reply",
    "payload": {
      "subject": "Question about pricing",
      "from": "[email protected]",
      "to": "[email protected]",
      "sent_at": "2026-07-05T15:30:00Z",
      "text": "Can you send me pricing for the monthly plan?",
      "history": [
        {
          "role": "customer",
          "text": "I saw your assistant on the website."
        }
      ]
    },
    "metadata": {
      "source": "supportdesk"
    }
  }'

Example Response

{
  "ok": true,
  "reply_id": 381,
  "conversation_id": 914,
  "message_id": 1822,
  "agent_run_id": 771,
  "external_thread_id": "email-thread-123",
  "external_message_id": "email-message-456",
  "suggested_response": {
    "text": "Thanks for reaching out. Pricing depends on the setup you need, so the best next step is to book a quick discovery call."
  },
  "references": [],
  "source_links": [],
  "memory_recall_trace_id": null,
  "answer_mode": "facts",
  "answer_intent": "answer_business_question",
  "generated_by_ai": true,
  "usage": {
    "model": "gpt-example",
    "input_tokens": 1200,
    "output_tokens": 90,
    "total_tokens": 1290
  }
}

Save message_id. You need it if you send feedback.

Multi-Turn Threads

Use the same external_thread_id for each turn in the same external conversation.

{
  "external_thread_id": "email-thread-123",
  "external_message_id": "email-message-789",
  "idempotency_key": "reply-email-message-789",
  "payload": {
    "text": "Do you offer annual billing?",
    "history": [
      {
        "role": "assistant",
        "text": "Thanks for reaching out. Pricing depends on the setup you need."
      }
    ]
  }
}

Bombyx reuses the prior external conversation when it sees the same organization, connector, chatbot, and external_thread_id.

Safe Retries

Use a safe retry key, called idempotency_key, when you retry the same external message.

Also send external_message_id when your system has one.

What happens:

If the first request completed, Bombyx returns the same reply with 200.
If a matching request exists but did not complete, Bombyx returns 409.
If neither key has been seen, Bombyx creates a new reply.

Send Feedback

Send feedback after a human accepts, rejects, or corrects the suggested response.

curl https://bombyxlabs.com/app/api/tool-connectors/v1/assistant/replies/1822/feedback \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "down",
    "feedback_kind": "answer_correction",
    "feedback_issue": "not_factually_correct",
    "suggested_answer": "Tell the customer that annual billing is available after onboarding.",
    "note": "The original answer missed annual billing.",
    "external_feedback_id": "feedback-abc-123"
  }'

Example response:

{
  "ok": true,
  "rating": "down",
  "feedback_id": 222,
  "response_review_id": 88
}

A downvote can create a review item for training. That review still follows Bombyx’s normal safety and approval flow.

Common Mistakes

Treating the response as already sent. It is only a suggested response.
Changing external_thread_id on each email in the same thread.
Retrying without idempotency_key or external_message_id.
Sending feedback for a message that was not created by this external assistant endpoint.