O SDK de Python

Comece aqui

Se nunca utilizou o Conecto, esta secção contém todo o modelo mental. Cinco minutos aqui tornam evidente o resto da página.

O que é o Conecto

Um widget de chat no seu site. Os visitantes escrevem nele; a sua equipa, um agente de IA ou o seu próprio código responde. Tudo o que se segue é uma forma de colocar o seu código nesse ciclo.

Os cinco substantivos

Quase todos os métodos deste SDK recebem ou devolvem um destes elementos.

As três coisas que pode criar

Bot ou plugin? Se quiser escrever as palavras que o visitante lê, crie um bot. Se preferir deixar a IA falar e apenas lhe dar acesso aos seus dados, como encomendas, subscrições e stock, crie um plugin. A maioria das equipas acaba por precisar de um plugin.

Palavras utilizadas nesta página

Jargão definido uma única vez. Nada aqui é específico do Conecto, exceto os dois últimos termos.

De que secção preciso?

Instalar e autenticar

pip install conecto

Crie uma credencial em Definições → Programadores. Recebe um ID de cliente (ck_…) and a segredo (cs_…). The secret is shown once and stored hashed, so put it somewhere your code can read and your repository cannot.

export CONECTO_CLIENT_ID=ck_your_client_id
export CONECTO_SECRET=cs_your_secret

from conecto import Conecto

client = Conecto()                    # reads the environment
client = Conecto("ck_...", "cs_...")  # or pass them directly

print(client.ping()["workspace"]["name"])

Call ping() once at startup. It raises AuthenticationError immediately if the credential is wrong or revoked — much better than finding out mid-conversation. A credential can cover the workspace or be scoped to one widget; a scoped one simply cannot see other widgets' conversations.

Início rápido

Três coisas que pode fazer nos primeiros cinco minutos.

Ler o que está a acontecer

for convo in client.conversations.list(status="open"):
    who = convo.visitor.email if convo.visitor else "anonymous"
    print(f"#{convo.id}  {who}  {convo.preview}")

Responder a alguém

convo = client.conversations.get(4821)
print(convo.messages[-1].body)          # what they said last
convo.reply("On it — give me one moment.")

Enviar algo que não seja texto

from conecto import blocks

convo.reply("Here's how to reset it:", blocks=[
    blocks.image("https://cdn.you.com/reset.gif", alt="Reset flow"),
    blocks.buttons([
        blocks.reply_button("That worked"),
        blocks.link_button("Full guide", "https://docs.you.com/reset"),
    ]),
])

Esta é a estrutura de toda a biblioteca: um cliente com recursos, objetos que sabem agir sobre si próprios e builders para tudo o que é estruturado.

O cliente

Crie um e mantenha-o. Reutiliza ligações e pode ser partilhado em segurança entre threads.

client = Conecto(
    client_id="ck_...",
    secret="cs_...",
    base_url="https://conecto.chat/api/v1",  # override for staging
    timeout=30.0,        # seconds per request
    max_retries=2,       # timeouts, 429s and 5xx
    app="acme-billing",  # added to the User-Agent; shows up in our logs
)

Ambiente

Recursos

Desvio entre versões

Cada resposta inclui a versão da API do servidor. Registe-a no arranque. Se mudar e desaparecer um campo que utiliza, esta será a primeira informação de que vai precisar.

print(client.api_version)   # what the server last reported
print(client.sdk_version)   # what this SDK was built against

limits = client.meta.schema()["limits"]
assert limits["blocks_per_message"] >= 4

client.meta.schema() devolve toda a API em JSON, incluindo endpoints, eventos, tipos de bloco, ações reservadas, códigos de erro e todos os limites. É servido pelo mesmo código que aplica essas regras, pelo que não se pode afastar da realidade.

Conversas

A thread between a visitor and your workspace. Messages have a sender de visitor, agent, bot ou system.

Listar e ler

page = client.conversations.list(status="open", limit=25)

page.items                     # this page only
for convo in page:             # every page, fetched lazily
    ...

convo = client.conversations.get(4821)
convo.status, convo.visitor.email, convo.messages[-1].body

# Poll cheaply: only what is newer than what you already have.
fresh = client.conversations.messages(4821, since_id=last_seen_id)

Responder

convo.reply("I can refund order #1284 — confirm?",
            buttons=["Yes, refund it", "Talk to a human"])

Um toque num botão de resposta rápida regressa como uma mensagem normal do visitante com esse texto, por isso o seu handler não precisa de um caso especial.

Orientação do tópico

convo.typing()                  # "…is typing", expires after ~8s
convo.reply("Working on it…")

convo.reply("Escalating: refund over policy limit.", internal=True)
convo.handoff()                 # flag for a human; routing rules apply
convo.assign(user_id=12)        # ids come from client.members.list()

convo.close()
convo.reopen()

Writing to a closed thread raises ConversationClosed. Reopen it first, or catch it — see Erros.

Conteúdo enriquecido

Qualquer mensagem pode incluir até dez blocos: imagens e GIFs, vídeo, áudio, ficheiros, conteúdos incorporados de terceiros, carrosséis de cartões, listas de etiquetas e valores, botões e separadores. São apresentados no widget e na caixa de entrada do agente.

Os blocos são dicionários simples durante a transmissão, pelo que pode escrevê-los manualmente. Os builders existem porque uma chave mal escrita acaba por levar um cliente a dizer que a imagem nunca apareceu. Aplicam as mesmas regras do servidor no ponto em que o traceback ainda aponta para o seu código.

from conecto import blocks

convo.reply("Here's your order:", blocks=[
    blocks.list_block([
        blocks.row("Placed", "12 July 2026"),
        blocks.row("Status", "Shipped"),
        blocks.row("Carrier", "DHL", subtitle="Tracking 4Z8871",
                   url="https://track.dhl.com/4Z8871"),
    ], title="Order #1042"),
    blocks.divider(),
    blocks.cards([
        blocks.card("Trail Runner 2",
                    subtitle="Road · Neutral",
                    price="89.00 USD",
                    badge="Back in stock",
                    image="https://cdn.you.com/tr2.jpg",
                    url="https://shop.you.com/p/tr2",
                    buttons=[blocks.link_button("Buy", "https://shop.you.com/cart")]),
    ]),
])

Todos os tipos de bloco

Dois tipos de botão

blocks.reply_button("Yes, refund it")                    # sends that text back
blocks.reply_button("Yes, refund it", "confirm_refund")  # nice label, stable value
blocks.link_button("Read the policy", "https://you.com/refunds")  # opens a tab

Atribua um valor explícito a um botão de resposta quando a etiqueta deve ser clara, mas o texto que o bot reconhece não deve mudar sempre que alguém altera o conteúdo.

Enviar um GIF

A .gif works. A muted, looping, autoplaying video is usually the better trade — a fraction of the bytes, and nobody can tell.

blocks.video("https://cdn.you.com/reset.mp4",
             autoplay=True, loop=True, muted=True)

Regras aplicadas pelos builders

• Every URL must be https. The widget runs on an https page, so anything else is blocked by the browser anyway.
• Dez blocos por mensagem, dez cartões, doze linhas de lista e seis botões.
• Long strings are truncated, not rejected. Structural mistakes raise BlockError.
• A YouTube link in a video block raises, and tells you to use embed.

A validação ocorre localmente. reply(blocks=…) checks the list before sending, so a typo raises BlockError from your line rather than coming back as an HTTP 400 from inside the client.

Upload de ficheiros

Não existe um URL público para esse GIF, recibo ou ficha técnica? Faça o upload, até 10 MB, e utilize o resultado.

media = client.media.upload("celebrate.gif")     # a path
media = client.media.upload(open("a.pdf", "rb")) # a file object
media = client.media.upload(raw_bytes, filename="receipt.png")

convo.reply("All set!", blocks=[blocks.image(media)])

A Media can be passed straight to blocks.image, blocks.video ou blocks.file.

Use media.url, not media.absolute_url. url é um caminho resolvido pelo widget em relação à sua própria origem, pelo que a mesma mensagem funciona em desenvolvimento, num deployment de pré-visualização e em produção, mesmo quando o seu domínio mudar.

Contactos e visitantes

Contactos

The CRM. upsert is keyed on email, so it is safe to point a nightly sync at.

client.contacts.upsert(
    "maya@acme.io",
    name="Maya Silva",
    company="Acme",
    custom_fields={"plan": "scale", "mrr": "480"},
)

contact = client.contacts.find("maya@acme.io")     # or None
for c in client.contacts.list(query="acme"):
    print(c.email, c.custom_fields.get("plan"))

custom_fields é combinadas, não substituídas. Dois processos podem gerir as suas próprias chaves sem se sobreporem. Até 30 chaves por chamada.

Visitantes

A browser session on a widget, keyed by (widget_id, session). The session id lives in the visitor's browser; read it client-side and send it to your backend.

visitor = client.visitors.get(widget_id=7, session=session_id)
visitor.email, visitor.verified

Mensagens proativas

Envie para uma sessão sem esperar que lhe perguntem, por exemplo atualizações de envio, lembretes de trial ou recuperação de carrinho.

client.visitors.message(
    widget_id=7, session=session_id,
    body="Still thinking it over? Your cart is saved:",
    blocks=[blocks.cards([
        blocks.card("Trail Runner 2", price="89.00 USD",
                    image="https://cdn.you.com/tr2.jpg",
                    url="https://shop.you.com/cart"),
    ])],
)

Reutiliza a conversa ativa da sessão ou abre uma nova. Um widget aberto mostra-a na próxima consulta; um widget fechado mostra-a quando voltar a abrir, assinalada como não lida.

Tickets e artigos

Tickets

ticket = client.tickets.create(
    email="maya@acme.io",
    message="Card was declined on renewal.",
    priority="high",          # low · normal · high · urgent
)

client.tickets.update(ticket.id, status="pending", assignee_user_id=12)
ticket.reply("We've fixed the card on file — try again?")   # emails the requester
ticket.reply("Billing confirmed the retry.", internal=True)  # private note

Uma resposta pública reabre um ticket resolvido, porque responder a algo marcado como concluído quase sempre inicia uma nova interação.

Artigos do centro de ajuda

Útil nos dois sentidos: pesquise a partir de um bot antes de abrir um ticket e envie documentação a partir da ferramenta em que a escreve.

hits = client.articles.list(query="refund", published=True)
if hits:
    convo.reply(f"This might help: “{hits[0].title}”")

client.articles.create("Shipping times", "<p>2-4 business days.</p>",
                       published=True)

O HTML é limpo no servidor com base numa lista de tags seguras, através do mesmo processo utilizado pelo editor do dashboard. Scripts e estilos são removidos antes de qualquer conteúdo ser guardado.

Criar um bot

A bot is a webhook and a reply. Bot handles the five things that are easy to get subtly wrong — signature verification, delivery deduplication, event routing, filtering out your own messages, and answering fast — so your code is the part that is yours.

from conecto import Conecto, Bot, blocks

client = Conecto()
bot = Bot(client, secret=WEBHOOK_SECRET)

@bot.on_message
def handle(ctx):
    text = ctx.text.lower()

    if "human" in text:
        ctx.reply("Of course — connecting you now.")
        ctx.handoff()
        return

    if "order" in text:
        if not ctx.verified:
            ctx.reply("What's the email on the order?", ask_email=True)
            return
        order = lookup_order(ctx.verified_email)     # your system
        ctx.reply("Here it is:", blocks=[
            blocks.list_block([
                blocks.row("Status", order["status"]),
                blocks.row("Carrier", order["carrier"]),
            ], title=order["number"]),
        ])
        return

    ctx.reply("I'm not sure about that one — let me get someone who is.")
    ctx.note(f"Bot could not classify: {ctx.text!r}")
    ctx.handoff()

Disponibilização

# Flask
app.add_url_rule("/conecto", view_func=bot.flask_view(), methods=["POST"])

# FastAPI (handlers run in a worker thread, so they never stall the loop)
app.post("/conecto")(bot.fastapi_route())

# Django (urls.py)
path("conecto/", csrf_exempt(bot.django_view()))

# No framework at all
from wsgiref.simple_server import make_server
make_server("", 8000, bot.wsgi_app()).serve_forever()

Depois subscreva o endpoint:

hook = client.webhooks.create(
    "https://bots.you.com/conecto",
    ["message.created", "conversation.created", "conversation.rated"],
)
print(hook.secret)   # store this — it is how you verify deliveries

Handlers

O que um handler recebe

Executa mais do que um worker? Deduplication is in-process by default, so two workers can each handle the same delivery once. Pass your own store — anything with add(id) -> bool, backed by Redis or your database.

class RedisSeen:
    def add(self, delivery_id):
        # True if new, False if we have handled it before
        return bool(redis.set(f"conecto:{delivery_id}", 1, nx=True, ex=86400))

bot = Bot(client, secret=WEBHOOK_SECRET, seen=RedisSeen())

Criar um plugin

Um bot responde a webhooks. Um plugin funciona no sentido oposto: declara o que os seus sistemas podem fazer e o agente de IA decide quando os utilizar enquanto fala com alguém. Nunca escreve a lógica da conversa, apenas a consulta.

É assim que uma loja, sistema de faturação ou CRM que não conhecemos se torna uma integração de primeira classe.

from conecto import Conecto, Plugin, parameter

plugin = Plugin("acme-store", base_url="https://api.acme.com/conecto")

@plugin.action(
    "catalog.search_products",
    description="Search the Acme catalog by keyword.",
    parameters=[parameter("query", required=True,
                          description="Search words from the visitor.")],
)
def search(req):
    hits = catalog.search(req.get("query"), limit=req.get("limit", 4))
    if not hits:
        return req.not_found()
    return req.ok(products=[
        {"title": p.name, "url": p.url, "image": p.image,
         "price_from": f"{p.price:.2f}", "currency": "USD",
         "available": p.stock > 0}
        for p in hits
    ])

@plugin.action(
    "orders.get_status",
    risk="verified_read",
    description="Status of one of the visitor's own orders.",
    parameters=[parameter("order_number", required=True)],
)
def order_status(req):
    order = orders.find(req.get("order_number"), email=req.verified_email)
    return req.ok(**order) if order else req.not_found()

Disponibilizar e registar

# One route serves every action.
app.add_url_rule("/conecto/<path:action>", view_func=plugin.flask_view(),
                 methods=["POST"])

# Tell Conecto it exists. Idempotent — run it on every release.
integration = plugin.deploy(Conecto())
print(integration.signing_secret)   # set this in your environment

deploy() cria ou atualiza a integração para corresponder ao seu código, elimina as ações que removeu e instala-a nos seus widgets. Nada fica exposto à IA antes da instalação.

As cinco respostas

return req.ok(status="Shipped", carrier="DHL")   # success
return req.ok(result, blocks=[...])              # …plus rich content in the reply
return req.not_found()                           # nothing matched — a normal outcome
return req.verify_required()                     # "I need a proven identity"
return req.error("That subscription was already cancelled.")

Write error messages for the visitor, not for your logs: the AI may relay them. Returning a plain dict is also fine — it is treated as the result.

Níveis de risco

req.verified_email é a única identidade em que deve confiar. An email in req.arguments is whatever the model parsed out of a chat. For verified_read e write the platform will not call you at all until we have proven who the visitor is, and the proven address is the one we hand you.

Ações reservadas

Alguns nomes têm um significado próprio para a plataforma. Declare um deles e o seu serviço fica ligado à funcionalidade que já existe para esse nome.

Teste antes de um visitante o fazer

client.integrations.run("acme-store", "catalog.search_products",
                        {"query": "trail shoes"})
# {'status': 'ok', 'result': {...}, 'blocks': []}

Isto executa o real call path — the signature, your credential, the checks that stop your URL pointing anywhere private, the timeout, the parsing — so what you see is exactly what the AI will get. Pass conversation_id= to run in the context of a live chat, which is the only way a verified action can succeed.

Escrever uma boa descrição

O description is the highest-leverage string in your integration: it is what the AI reads to decide whether this action answers the question in front of it. Write it as an instruction to a capable colleague who cannot see your code.

Fraco: «Consultar encomenda.»
Forte: «Consulte o estado e a data de entrega de uma encomenda do próprio visitante através do respetivo número. Utilize esta ação sempre que a pessoa perguntar onde está algo ou quando irá chegar.»

O que a plataforma garante

• 8 segundos timeout, 128 KB limite da resposta.
• Calls are signed with your signing_secret — same scheme as webhooks.
• O seu URL é resolvido uma vez e fixado a um IP público; os redirecionamentos são recusados.
• Tudo o que devolve chega ao modelo como dados, nunca como instruções, e as chaves que parecem conter secrets são removidas.
• As integrações personalizadas exigem um plano pago com Agente de IA. São permitidas 20 por espaço de trabalho e 40 ações em cada uma.

Identidade

Tudo o que envolve os dados de uma pessoa aguarda até sabermos quem ela é. Isso acontece de uma de duas formas: através de um código enviado por e-mail ou de a confirmação do seu site para um utilizador que já tem sessão iniciada.

# your backend, right after your own auth check
client.visitors.identify(
    widget_id=7,
    session=conecto_session,          # read from the visitor's browser
    email=user.email,
    name=user.name,
    verified=True,                    # the vouch
    verify_hours=24,                  # max 72, default 12
    data={"plan": user.plan, "customer_since": "2024"},
)

# when they log out
client.visitors.unverify(widget_id=7, session=conecto_session)

Enquanto a confirmação for válida, o Conecto considera o e-mail confirmado: o widget conhece o nome da pessoa, os chats são associados ao contacto correto e os fluxos que, de outro modo, exigiriam um código por e-mail, como consultas de encomendas, reembolsos, dados da conta ou ações verificadas do seu plugin, avançam sem esse código.

Confirme apenas sessões que o seu backend tenha realmente autenticado. A sua confirmação é considerada tão forte como o nosso próprio código por e-mail, porque autenticou realmente a pessoa. Tem duração limitada e está associada à sessão, por isso um novo browser precisa de uma nova confirmação. O browser nunca se pode marcar como verificado; essa chamada é autenticada e deve ser feita no seu servidor.

Webhooks e eventos

Bot faz tudo isto por si. Utilize os helpers de baixo nível quando quiser verificar na periferia e processar numa fila.

from conecto import webhooks

event = webhooks.parse(request.get_data(), request.headers, secret=SECRET)

event.id                  # the delivery id — dedupe on this
event.event               # "message.created"
event.conversation_id
event.text
event.is_visitor_message  # excludes your own bot's messages
event.visitor.verified

Verificar com base no corpo original. Re-serializing JSON changes the bytes and the signature stops matching — this is the most common first-integration bug there is. Use request.get_data() in Flask, request.body in Django, await request.body() in FastAPI. Passing a parsed dict raises with this exact advice.

Eventos

Semântica das entregas

As entregas são feitas pelo menos uma vez e sem ordem garantida: if we cannot confirm you got one we send it again, and they will not always arrive in the order things happened. They also time out after 2.5 seconds — so answer 200 immediately and do the work afterwards.

• Every payload carries an id (also in X-Conecto-Delivery). Store it and skip ids you have already handled.
• Pass that same id as idempotency_key when you reply, and a redelivery can never make your bot speak twice.
• X-Conecto-Timestamp permite rejeitar entregas antigas; por predefinição, o SDK verifica-as com uma tolerância de cinco minutos.

signature = webhooks.sign(SECRET, raw_body)      # what we send
webhooks.verify(raw_body, header_value, SECRET)  # True / False, never raises

Chamadas de integração que fazemos às your plugin use the identical scheme with the integration's signing_secret — one verification routine covers both directions.

Erros e novas tentativas

Every failure raises a subclass of ConectoError, so you can catch exactly what you expect.

from conecto import ConversationClosed, RateLimited, NotFoundError

try:
    convo.reply("Refunded — you'll see it in 3-5 days.")
except ConversationClosed:
    convo.reopen()
    convo.reply("Refunded — you'll see it in 3-5 days.")
except NotFoundError:
    log.warning("conversation vanished")

Every exception carries code, message, status and the raw response.

Novas tentativas

Timeouts, rate limits (429) and server errors (5xx) are retried for you. Each retry waits a little longer than the last, with a random amount added so that a thousand clients recovering at once do not all come back in the same instant — and if we send a Retry-After, that wins.

As operações de escrita também são repetidas, o que normalmente seria perigoso. Aqui é seguro porque cada escrita inclui uma chave de idempotência e uma nova tentativa reutiliza a mesma chave. O servidor reconhece a segunda tentativa como a mesma chamada e não a repete.

client = Conecto(max_retries=0)   # opt out entirely

Limites que deve conhecer

client.meta.schema()["limits"] tem sempre os valores atuais.

Paginação

List endpoints return a Page you can use three ways.

page = client.contacts.list(query="acme")

page.items        # just this page — a list, so len() and [0] work
page.has_more     # is there another?

for contact in page:   # every page, fetched lazily as you consume
    ...

page.all()        # everything, collected into one list

Iterating is lazy: next(iter(page)) costs exactly one request no matter how many contacts exist. all() is fine for contacts and tickets; think twice on a busy workspace's conversations, where iterating and stopping early is usually what you meant.

A testar

The client takes a transport, which is the seam for tests. Anything with get, post, patch, delete e request works — no network, no credentials, no mocking library.

class FakeTransport:
    base_url = "https://conecto.test/api/v1"

    def __init__(self):
        self.calls = []
        self.responses = {}

    def request(self, method, path, **kw):
        self.calls.append((method, path, kw.get("json_body")))
        return self.responses.get(f"{method} {path}", {})

    def get(self, p, **kw): return self.request("GET", p, **kw)
    def post(self, p, json_body=None, **kw): return self.request("POST", p, json_body=json_body, **kw)
    def patch(self, p, json_body=None, **kw): return self.request("PATCH", p, json_body=json_body, **kw)
    def delete(self, p, **kw): return self.request("DELETE", p, **kw)


def test_bot_answers_refunds():
    transport = FakeTransport()
    client = Conecto(transport=transport)
    client.conversations.reply(1, "Refunded.")
    assert transport.calls[0][1] == "/conversations/1/messages/"

Para bots e plugins, desative a verificação de assinaturas nos testes em vez de assinar fixtures:

bot = Bot(client, verify=False)
plugin = Plugin("acme", base_url="https://x.test", verify_signatures=False)

Referência de métodos

Conversas

Contactos

Visitantes

Integrações

Tickets, artigos, widgets, multimédia, webhooks e metadados

Modelos

Every returned object keeps the payload it was built from. Attribute access is the nice path; obj.raw is always there for a field this SDK version does not know about yet, so a release is never what stands between you and a new API field.

convo.status          # typed
convo.raw["status"]   # the same thing
convo["status"]       # shorthand for the raw payload
convo.to_dict()       # exactly what the API sent

Receitas

Evitar um ticket com o seu centro de ajuda

@bot.on_message
def deflect(ctx):
    hits = ctx.client.articles.list(query=ctx.text, published=True)
    if hits:
        ctx.reply(f"This might help: “{hits[0].title}”. Did that solve it?",
                  buttons=["Solved it", "Open a ticket"])
    else:
        ctx.reply("Let's get this to the team.", ticket_form=True)

Qualificar um lead e encaminhá-lo

@bot.on_message
def qualify(ctx):
    if not ctx.event.visitor or not ctx.event.visitor.email:
        ctx.reply("Happy to help — what's your work email?", ask_email=True)
        return

    ctx.client.contacts.upsert(
        ctx.event.visitor.email,
        custom_fields={"lead_source": "chat", "intent": classify(ctx.text)},
    )
    ctx.note("Qualified lead — routing to sales.")
    ctx.assign(SALES_USER_ID)
    ctx.handoff()

Recuperar uma classificação negativa

@bot.on_rating
def follow_up(ctx):
    rating = ctx.event.rating or {}
    if rating.get("score", 5) <= 2:
        ctx.client.tickets.create(
            email=ctx.event.visitor.email,
            message=f"Low CSAT ({rating['score']}/5): {rating.get('comment', '')}",
            priority="high",
        )

Sincronização noturna de contactos

for user in your_database.active_users():
    client.contacts.upsert(
        user.email, name=user.name, company=user.company,
        custom_fields={"plan": user.plan, "mrr": str(user.mrr)},
    )

Uma loja que não conhecemos

@plugin.action("catalog.search_products",
               description="Search the catalog by keyword.",
               parameters=[parameter("query", required=True)])
def search(req):
    hits = your_catalog.search(req.get("query"))
    return req.ok(products=[to_conecto(p) for p in hits]) if hits else req.not_found()

Esta é toda a integração. Os cartões de produto, a montra da página inicial e a regra que impede o modelo de colar URL em bruto são incluídos com o nome reservado.

Está a desenvolver algo? Fale connosco , queremos que as pessoas criem com o Conecto e damos prioridade ao que os programadores pedem. O SDK tem licença MIT e é open source; issues e pull requests são bem-vindos no GitHub.