letterbook-ai-chat 1.1.0

Python SDK for sending AI chat turns and explicit support conversations to Letterbook

Letterbook Python SDK

Send AI chat turns or explicit support events to Letterbook so customer issues become conversations.

Turn-based detection

Each record_turn call captures one turn in the conversation. It does not create a ticket by itself. Letterbook queues the turns, waits for the conversation to go quiet, scans the transcript on the backend with an LLM, and creates a ticket only when it finds a relevant customer issue.

import letterbook

result = letterbook.record_turn(
    user_id="user123",
    event="user_message",
    model="gpt_4",
    input="The checkout page is broken and I was charged twice.",
    output="I am sorry, I cannot fix billing issues from here.",
    convo_id="conv789",
    customer_email="[e-mail]",
    debounce_seconds=300,
    properties={
        "system_prompt": "you are a helpful assistant",
        "experiment": "experiment_a",
    },
    attachments=[
        {
            "type": "text",
            "name": "Additional Info",
            "value": "A very long document",
            "role": "input",
        }
    ],
)

print(result.queued, result.evaluation_after_seconds)

Set LETTERBOOK_API_KEY, or instantiate letterbook.Letterbook(api_key=...) for explicit configuration. Set debounce_seconds to control how long Letterbook waits after the last message before evaluating the conversation. If OpenTelemetry is configured in your app, the SDK automatically propagates the active trace context with each capture request. You can install letterbook-ai-chat[otel] if your app does not already include OpenTelemetry.

If customer_email is omitted, the SDK looks for properties["customer_email"], properties["email"], or an email-shaped user_id. Email is only required if Letterbook promotes the capture to a ticket.

letterbook.capture_turn(...) and letterbook.capture(...) are deprecated compatibility aliases for letterbook.record_turn(...).

Push-based conversation creation

When your app already knows a tool call should create a support conversation, call create_conversation directly.

conversation = letterbook.create_conversation(
    customer_email="[e-mail]",
    customer_name="Customer",
    subject="Checkout tool failed",
    message="The checkout tool failed after charging the card twice.",
    priority="high",
    external_id="tool-call-123",
    metadata={
        "source": "ai_tool",
        "session_id": "session_789",
    },
)

print(conversation.id, conversation.url)

API-key REST helpers

The SDK also wraps the existing API-key endpoints:

letterbook.list_conversations(status="open", page_size=50)
letterbook.get_conversation("conv_123")
letterbook.add_conversation_note(
    "conv_123",
    author_email="[e-mail]",
    content="Investigated from the external workflow.",
    mentioned_user_emails=["[e-mail]"],
)
letterbook.delete_user("user_123", confirm_email="[e-mail]")

Framework adapters

Framework adapters are optional and do not add hard dependencies to the base SDK. Install the framework package separately, then import adapters from letterbook.integrations. Pass a stable convo_id such as your chat session, thread, or conversation id when using turn-based detection. Framework run/event ids are per model call and are not used as fallbacks because they split one transcript into separate evaluations.

LangChain:

from langchain_openai import ChatOpenAI
from letterbook.integrations import create_langchain_callback_handler

handler = create_langchain_callback_handler(
    user_id="user123",
    model="gpt_4",
    convo_id="conv789",
    customer_email="[e-mail]",
)

model = ChatOpenAI(callbacks=[handler])

LlamaIndex:

from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from letterbook.integrations import create_llamaindex_callback_handler

handler = create_llamaindex_callback_handler(
    user_id="user123",
    model="gpt_4",
    convo_id="conv789",
    customer_email="[e-mail]",
)

Settings.callback_manager = CallbackManager([handler])