sdk-python

synquic-slide is the official Python SDK for the Slide by Synquic API, a multi-channel customer engagement platform. One client covers WhatsApp Business messaging, SMS, RCS, OTP verification, transactional email, Instagram DMs, one send call across those channels, AI voice calls, Shopify lookups, unified contacts, automations and outbound webhooks. It targets server-side Python 3.9+ and ships a synchronous client and an identical async one, both built on httpx. It authenticates with a secret API key, so it belongs on your backend, never in a client application.

Installation

pip install synquic-slide

Quick start

Responses are plain dictionaries (typed as TypedDict), so read them with ["key"].

import os
from synquic_slide import SlideClient

slide = SlideClient(api_key=os.environ["SLIDE_API_KEY"])

# WhatsApp template message
msg = slide.whatsapp.send_template(
    to="+919876543210",
    template_name="order_shipped",
    language_code="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "#1042"}]}],
)
print(msg["wamid"], msg["conversationId"])

# Transactional email from a saved template
slide.email.send(
    recipient={"to": "customer@example.com", "firstName": "Priya"},
    template_id="tmpl_order_confirm",
    from_name="Acme Store",
    from_email="orders@acme.com",
    variables={"orderId": "#1042"},
)

# Paginated reads always return {"data": [...], "meta": {...}}
page = slide.contacts.list(page=1, limit=50, search="priya")
print(len(page["data"]), page["meta"]["totalPages"])

# Outbound AI voice call. Failures raise SlideValidationError, SlideAuthError, etc.
call = slide.voice.initiate_outbound_call(
    agent_id="agent_abc123",
    to_number="+919876543210",
    call_context={"orderId": "#1042"},
)
print(call["id"], call["status"])

slide.close()   # or use `with SlideClient(api_key=...) as slide:`

The async client exposes exactly the same resources and method names:

import asyncio, os
from synquic_slide import AsyncSlideClient

async def main():
    async with AsyncSlideClient(api_key=os.environ["SLIDE_API_KEY"]) as slide:
        agents = await slide.voice.list_agents(page=1, limit=20)
        print([a["name"] for a in agents["data"]])

asyncio.run(main())

Verifying an incoming webhook delivery. Pass the raw body, never a re-serialised dict:

import os
from flask import request
from synquic_slide import construct_event, SlideSignatureVerificationError

@app.post("/webhooks/slide")
def slide_webhook():
    try:
        event = construct_event(
            request.get_data(),                        # not request.json
            request.headers["X-Slide-Signature"],
            os.environ["SLIDE_WEBHOOK_SECRET"],
        )
    except SlideSignatureVerificationError:
        return "bad signature", 400
    enqueue(event)          # event["id"] is stable across retries: dedupe on it
    return "", 200

One send call, contacts and automations

# One send call for any channel, with a fallback
sent = slide.messages.send(
    to="+919876543210",
    channel="whatsapp",
    fallback_channels=["sms"],
    message="Your order #1042 has shipped.",
    template={"name": "order_shipped", "languageCode": "en"},
    sms={"senderId": "ACMEIN"},
)
print(sent["channelUsed"], sent["messageId"], sent["attempts"])

# A new automation is always created paused. Going live is its own call.
catalog = slide.automations.node_catalog()   # trigger types, node types, their settings
automation = slide.automations.create(
    name="Order follow-up",
    trigger={"type": "WEBHOOK"},
    steps=[{"order": 0, "type": "SMART_DELAY", "delayMinutes": 5}],
)
slide.automations.activate(automation["id"])

# The AI models your workspace can use, with their prices
models = slide.ai.list_models()["data"]

# Create a contact, or update the one with the same phone or email.
# The API key needs the permission contacts:write.
contact = slide.contacts.upsert(
    phone="+919876543210",
    email="priya@example.com",
    name="Priya Sharma",
    tags=["Newsletter"],
)
print(contact["id"], contact["created"])

# Find one person: phone and email match exactly, search is a "contains" match
found = slide.contacts.list(email="priya@example.com")
same = slide.contacts.get(contact["id"])

The SDK makes every call once and never retries on its own. Do not retry a send blindly either: a timeout does not mean the message was not sent, and a second send reaches a real person twice.

contacts.upsert needs an API key with the permission contacts:write (and contacts.list / contacts.get need contacts:read). A key that only has the email list permission cannot create contacts: it is refused with SlideScopeError (403). A key's permissions cannot be edited, so create a new API key that has contacts:write.

Sending the same contacts.upsert again after it has answered, also after a timeout or a server error, gives the same contact and creates nothing twice. Two calls for the same person made at the same moment can be refused with SlideError status 409, and error.body["code"] says what to do: on CONTACT_UPSERT_IN_PROGRESS nothing was written, so wait error.body["retryAfter"] seconds and send it again; on PHONE_IN_USE send it again once.

Chat inside your own app

Your server makes one call: a short-lived chat token for a user it has already signed in. Your app opens the chat with that token. The API key never leaves your server.

Pilot: slide.chat is not in the version of this package on the registry yet. During the pilot you receive a build that has it with your pilot access; until then the token call is one plain POST /v1/chat/tokens with your key.

import os
from flask import Flask, jsonify, request
from synquic_slide import SlideClient, construct_event, SlideSignatureVerificationError

app = Flask(__name__)
slide = SlideClient(api_key=os.environ["SLIDE_API_KEY"])   # needs the scope chat:tokens:write

# 1. Your app asks YOUR server for a token, behind your own sign-in.
@app.get("/me/chat-token")
@require_sign_in
def chat_token():
    result = slide.chat.create_token(
        user_id=current_user.id,      # your own stable id for the user
        name=current_user.name,       # optional: how the team sees them
        role="patient",               # optional
        app="patient",                # optional: only when you have more than one app
    )
    return jsonify(token=result["token"])   # to refresh, the app simply asks again

# 2. A reply is waiting for a user who has not seen it: send your own push.
@app.post("/webhooks/slide-chat")
def chat_webhook():
    try:
        event = construct_event(
            request.get_data(),
            request.headers.get("X-Slide-Signature", ""),
            os.environ["SLIDE_CHAT_WEBHOOK_SECRET"],
        )
    except SlideSignatureVerificationError:
        return "bad signature", 400
    if event["type"] == "chat.message.unread":
        data = event["data"]      # never carries the text; de-duplicate on data["messageId"]
        enqueue_push(data["userId"], data["app"], badge=data["unreadCount"])
    return "", 200

Optional, when a user signs out or asks to be erased: slide.chat.revoke_user(user_id, app=...) and slide.chat.delete_user(user_id, app=...) (scope chat:users:write).

API reference

Every method below exists twice: on SlideClient (blocking) and on AsyncSlideClient (awaitable, same name). Arguments are keyword-only unless shown positionally. List methods also accept page (default 1) and limit (default varies by endpoint, 10 to 50).

Module-level exports

Failed requests raise SlideValidationError (400), SlideAuthError (401), SlideScopeError (403), SlideNotFoundError (404) or the base SlideError for any other status. All carry .status_code, .body and the API's message. Response TypedDicts such as Contact, VoiceCall and WhatsAppLog are importable from the package root.

Configuration

Webhook signing secrets are separate from the API key: webhooks.create() returns one once, and that is what construct_event and verify_webhook_signature expect (for example from SLIDE_WEBHOOK_SECRET).

Requirements

• Python >= 3.9
• httpx >= 0.27.0, the only declared dependency
• typing_extensions is imported by synquic_slide.types, and normally arrives transitively with httpx. Install it explicitly if your environment prunes transitive dependencies

Development

The project builds with the hatchling backend declared in pyproject.toml:

pip install -e .
python -m build      # produces the wheel and sdist

The chat resource and the chat.message.unread event have tests in tests/test_chat.py, on the standard library's unittest with the HTTP layer replaced, so nothing leaves the machine:

python3 -B -m unittest discover -s tests -v

The messages, automations, ai and contacts resources are covered the same way (tests/test_messages.py, tests/test_automations.py, tests/test_ai.py, tests/test_contacts.py): every method is checked on both clients for its HTTP method, path, query and body.

No linter or formatter configuration is checked in to this repository.

Licence

MIT.