fluidtalk 1.0.3

Official Python client for the FluidTalk Handshake API — drop FluidTalk AI persona replies into your own chatbot backend.

fluidtalk (Python)

Official Python client for the FluidTalk Handshake API. Drop FluidTalk's AI persona replies into your own chatbot backend without rebuilding the HTTP/auth/multipart layer.

You keep your own orchestration (when to open a chat, when to follow up, where to send messages); this client just gives you the persona's reply in one call.

pip install fluidtalk

⚠️ Server-side only. Use this from your backend. Never put your ft_sk_ key in frontend, browser, or mobile-client code — it would leak. Your server calls FluidTalk; your client calls your server.

from fluidtalk import FluidTalk, FluidTalkError

ft = FluidTalk(
    api_key="ft_sk_...",            # scoped to one persona + engine
    own_username="@my_account",     # optional default for tracking / dedup
    # base_url="https://api-talk.fluidvip.com"  (default)
)

# A lead messaged you -> get the persona's reply and relay it on your platform
res = ft.inbound_chat(target="@john_doe", message="hey, saw your post!")
for bubble in res.replies:
    my_chat.send("@john_doe", bubble)
if res.should_send_photo and res.photo_url:
    my_chat.send_image("@john_doe", res.photo_url)

Concepts → methods

A conversation can start four ways. The builder names map to these methods (the API wire value is handled for you):

Builder name	When	Method
Inbound Chat	the lead messages first (or an ongoing chat)	ft.inbound_chat(target, message)
AI Opener	your persona messages first	ft.ai_opener(target)
Event Trigger	a platform event fires	ft.event_trigger(target, event_type, context)
Follow-up	re-engage a quiet lead	ft.follow_up(target)
—	host a local image for context	ft.upload_image(path=...)

A conversation is keyed by (persona, target) — reuse the same target for the same lead and the engine keeps phase/state across turns.

An image (image_path or image_url) is accepted by inbound_chat, ai_opener, and event_trigger — not follow_up.

Examples

# AI opener (optionally with a profile screenshot for better targeting)
opener = ft.ai_opener(target="@lead", image_path="./profile.jpg")
my_chat.send("@lead", opener.message)

# Platform event (event_type must match an Event Trigger configured in your engine)
ev = ft.event_trigger(target="@lead", event_type="story_reaction", context={"reaction": "🔥"})

# Re-engage a ghost (needs an existing conversation)
fu = ft.follow_up(target="@lead")

# Attach an image the lead sent — from a local file path...
url = ft.upload_image(path="./incoming.jpg").url
r = ft.inbound_chat(target="@lead", message="what do you think?", image_url=url)

# ...or from bytes (e.g. a browser upload relayed to your backend, or serverless)
url = ft.upload_image(data=image_bytes, filename="lead.jpg").url

Results: inbound_chat → ChatResult(reply, replies, should_send_photo, photo_url, session_id, ignored, ignore_reason); ai_opener/event_trigger/follow_up → ActionResult(session_id, message, ignored, ignore_reason, continued, continued_reason); upload_image → UploadResult(url). Send replies as separate bubbles; when should_send_photo, also send photo_url.

Behaviour to handle

try:
    res = ft.inbound_chat(target="@lead", message="hi")
    if res.ignored:
        return  # duplicate lead, already owned by another account — send nothing
    for bubble in res.replies:
        my_chat.send("@lead", bubble)
except FluidTalkError as e:
    if e.status == 401:   # missing or invalid API key
        ...
    elif e.status == 402: # insufficient credits to start a new conversation — see your plan
        ...
    elif e.status == 400: # conversation already DONE / sealed -> stop messaging
        ...
    elif e.status == 404: # no conversation yet (follow_up before any contact)
        ...

• continued is True — the lead already had an active conversation, so the action continued it instead of starting fresh. For an opener (ai_opener) the message is then "" — send nothing. continued_reason tells you why (e.g. "conversation_already_active"). For event_trigger the event is folded into the ongoing chat and message is the reply.
• ignored is True — duplicate lead (already owned by another account of the persona). Send nothing.
• Sealed conversation — when finished, the next inbound_chat raises FluidTalkError(status=400) ("This session is DONE").

API keys are action-only: send messages and upload images, never change personas/engines/billing (that stays in the dashboard).