Official SDKs

Official libraries for Python and JavaScript/TypeScript. Fully typed, native async, built-in error handling.

pip install esignalnpm install @esignal/sdkNative TypeScript

Installation

pip install esignal
# With optional extras
pip install "esignal[async]"   # asyncio support
pip install "esignal[pandas]"  # DataFrame integration

Initialization

from esignal import Client

# Authenticate with an API key
client = Client(api_key="sk_live_xxx")

# Or via the ESIGNAL_API_KEY environment variable
client = Client()

Contacts

# List contacts
contacts = client.contacts.list(limit=50, channel="whatsapp")
for c in contacts:
    print(c.name, c.phone, c.score)

# Create a contact
contact = client.contacts.create(
    name="Kofi Asante",
    phone="+233241234567",
    channel="whatsapp",
    tags=["VIP", "Accra"]
)

# Retrieve a contact
contact = client.contacts.get("cnt_01J8X4...")

Conversations & Messages

# List open conversations
convs = client.conversations.list(status="open")

# Send a message
msg = client.conversations.send_message(
    conversation_id="conv_01J7P3...",
    content="Hello! How can I help you?"
)

# Retrieve the message history
messages = client.conversations.messages("conv_01J7P3...")

Analytics

from datetime import date

# Overview
overview = client.analytics.overview(
    from_date=date(2025, 11, 1),
    to_date=date(2025, 11, 30)
)
print(f"Revenue: {overview.revenue.attributed:,} XOF")
print(f"Leads: {overview.leads.converted}")

# AI forecast
forecast = client.analytics.forecast(horizon=90)
for point in forecast.data:
    print(point.date, point.revenue, point.lower, point.upper)

Webhooks (handler)

from flask import Flask, request
from esignal.webhooks import WebhookHandler

app = Flask(__name__)
handler = WebhookHandler(secret="whsec_xxx")

@handler.on("message.received")
def on_message(event):
    print(f"New message from {event.data.contact.name}")
    print(f"Content: {event.data.content}")
    print(f"Sentiment: {event.data.ai.sentiment}")

@app.route("/webhooks", methods=["POST"])
def webhooks():
    handler.process(request.data, request.headers)
    return "", 200

📖

API Reference

Complete endpoint documentation