Communications API

MYNDY_API_KEY=myndy_your_key_here
MYNDY_API_BASE=https://hello.myndy.ai/api/public/v1

curl https://hello.myndy.ai/api/public/v1/me \
  -H "X-API-Key: $MYNDY_API_KEY"

{
  "key_id": "a1b2c3d4",
  "key_name": "Partner Integration",
  "user_id": "user_123",
  "workspace_id": "ws_456",
  "scopes": [
    "calls:read", "calls:write",
    "contacts:read", "contacts:write",
    "conversations:read", "conversations:write",
    "messages:read", "messages:write",
    "numbers:read", "webhooks:manage"
  ],
  "rate_limit_per_minute": 100
}

{
  "numbers": [
    {
      "phone_number": "+15178880480",
      "status": "active",
      "is_default": true,
      "friendly_name": "primary"
    },
    {
      "phone_number": "+14722510252",
      "status": "active",
      "is_default": false,
      "friendly_name": "secondary"
    }
  ],
  "primary_number": "+15178880480",
  "total_count": 2
}

curl "https://hello.myndy.ai/api/public/v1/conversations?limit=25" \
  -H "X-API-Key: $MYNDY_API_KEY"

{
  "conversations": [
    {
      "contact_number": "+15551234567",
      "contact_name": "Jane Doe",
      "twilio_number": "+15178880480",
      "last_activity": "2026-08-14T18:04:11.482Z",
      "last_message_preview": "Are you open tomorrow?",
      "last_message_direction": "inbound",
      "unread_count": 2,
      "autopilot_disabled": false
    }
  ],
  "twilio_number": "+15178880480",
  "total_count": 42,
  "total_unread_count": 7,
  "has_more": true,
  "next_cursor": "eyJsYXN0X2FjdGl2aXR5Ijoi..."
}

curl "https://hello.myndy.ai/api/public/v1/conversations/%2B15551234567?limit=20" \
  -H "X-API-Key: $MYNDY_API_KEY"

{
  "contact_number": "+15551234567",
  "twilio_number": "+15178880480",
  "messages": [
    {
      "type": "sms",
      "direction": "inbound",
      "content": "Are you open tomorrow?",
      "message_sid": "SM1234567890abcdef",
      "timestamp": "2026-08-14T18:04:11.402Z",
      "sms_status": "delivered",
      "media_urls": [],
      "metadata": { "source": "sms" }
    },
    {
      "type": "call",
      "direction": "outbound",
      "call_sid": "CA1234567890abcdef",
      "call_status": "completed",
      "call_duration": 65,
      "recording_url": null,
      "timestamp": "2026-08-14T17:50:02.000Z"
    }
  ],
  "unread_count": 0,
  "has_more": false,
  "next_cursor": null
}

curl -X POST "https://hello.myndy.ai/api/public/v1/conversations/mark-all-read" \
  -H "X-API-Key: $MYNDY_API_KEY"

curl -X POST "https://hello.myndy.ai/api/public/v1/conversations/%2B15551234567/mark-unread" \
  -H "X-API-Key: $MYNDY_API_KEY"

curl -X POST https://hello.myndy.ai/api/public/v1/messages \
  -H "X-API-Key: $MYNDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Thanks for reaching out!"
  }'

{ "success": true, "message_sid": "SM1234567890abcdef" }

curl -X POST https://hello.myndy.ai/api/public/v1/calls/dial \
  -H "X-API-Key: $MYNDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567"}'

{ "success": true, "message": "Call initiated", "call_sid": "CA123..." }

npm install @twilio/voice-sdk

// app/api/myndy/voice-token/route.ts  (Next.js App Router)
export async function GET() {
  const res = await fetch(
    `${process.env.MYNDY_API_BASE}/calls/voice-token`,
    { headers: { "X-API-Key": process.env.MYNDY_API_KEY! } }
  );

  if (!res.ok) {
    return Response.json({ error: "token failed" }, { status: res.status });
  }

  // Only the token crosses to the browser — never the API key.
  const { token, identity } = await res.json();
  return Response.json({ token, identity });
}

import { Device } from "@twilio/voice-sdk";

async function fetchToken(): Promise<string> {
  const res = await fetch("/api/myndy/voice-token");
  const { token } = await res.json();
  return token;
}

export async function initDevice() {
  const device = new Device(await fetchToken(), {
    codecPreferences: ["opus", "pcmu"],
  });

  await device.register();

  device.on("incoming", (call) => {
    // call.accept() / call.reject()
  });

  // Tokens are short-lived; refresh before they expire.
  device.on("tokenWillExpire", async () => {
    device.updateToken(await fetchToken());
  });

  return device;
}

// Outbound call
export async function placeCall(device: Device, to: string) {
  return device.connect({ params: { To: to } });
}

{
  "contacts": [
    {
      "contact_id": "c_abc123",
      "name": "Jane Doe",
      "phone": "+15551234567",
      "email": "jane@example.com",
      "company_name": "Acme Inc",
      "notes": [],
      "tags": ["lead"],
      "custom_fields": [],
      "created_by": null,
      "user_id": "user_123",
      "workspace_id": "ws_456",
      "created_at_unix_secs": 1786651333,
      "updated_at_unix_secs": 1786651333
    }
  ],
  "total_count": 1,
  "total_pages": 1,
  "page": 1,
  "has_more": false
}

{
  "name": "Jane Doe",
  "phone": "+15551234567",
  "email": "jane@example.com",
  "company_name": "Acme Inc",
  "tags": ["lead"],
  "notes": [],
  "custom_fields": []
}

curl -X POST https://hello.myndy.ai/api/public/v1/webhooks \
  -H "X-API-Key: $MYNDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/api/myndy/webhook",
    "events": ["message.received", "call.missed"]
  }'

{
  "id": "b7c1f9d2-...",
  "url": "https://yourapp.com/api/myndy/webhook",
  "events": ["call.missed", "message.received"],
  "is_active": true,
  "created_at": "2026-08-14T18:00:00Z",
  "signing_secret": "myndy_wh-AbCdEf...",
  "consecutive_failures": 0
}

{
  "id": "evt_9f2c4a1b...",
  "event": "message.received",
  "created_at": "2026-08-14T18:04:11.482Z",
  "workspace_id": "ws_456",
  "data": {
    "from": "+15551234567",
    "to": "+15178880480",
    "body": "Are you open tomorrow?",
    "message_sid": "SM1234567890abcdef",
    "media_urls": [],
    "media_content_types": [],
    "channel": "sms",
    "timestamp": "2026-08-14T18:04:11.402Z"
  }
}

X-Myndy-Timestamp: 1786651333
X-Myndy-Signature: t=1786651333,v1=2275ca086b06f63eb647c0bc...

// app/api/myndy/webhook/route.ts
import crypto from "crypto";

function verify(rawBody: string, header: string | null, secret: string) {
  if (!header) return false;

  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=") as [string, string])
  );
  if (!parts.t || !parts.v1) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  if (a.length !== b.length) return false;

  // Constant-time compare avoids leaking the signature through timing.
  if (!crypto.timingSafeEqual(a, b)) return false;

  // Reject anything older than five minutes to blunt replay attacks.
  return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

export async function POST(request: Request) {
  // Read the raw body first — verification must run on exact bytes.
  const raw = await request.text();

  if (!verify(raw, request.headers.get("x-myndy-signature"), process.env.MYNDY_WEBHOOK_SECRET!)) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(raw);

  // Deliveries are at-least-once: dedupe on event.id before acting.
  switch (event.event) {
    case "message.received":
      // persist, push to your UI over your own websocket, etc.
      break;
    case "call.missed":
      break;
  }

  // Acknowledge fast; do slow work in a queue.
  return new Response("ok", { status: 200 });
}

import hashlib
import hmac
import json
import os
import time

from fastapi import APIRouter, HTTPException, Request

router = APIRouter()
SECRET = os.environ["MYNDY_WEBHOOK_SECRET"]


def verify(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False

    parts = dict(item.split("=", 1) for item in header.split(","))
    expected = hmac.new(
        SECRET.encode(),
        f"{parts['t']}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, parts.get("v1", "")):
        return False
    return abs(time.time() - int(parts["t"])) < 300


@router.post("/api/myndy/webhook")
async def myndy_webhook(request: Request):
    raw = await request.body()
    if not verify(raw, request.headers.get("x-myndy-signature")):
        raise HTTPException(status_code=401, detail="invalid signature")

    event = json.loads(raw)
    # Deduplicate on event["id"] — deliveries are at-least-once.
    return {"ok": True}

// lib/myndy.ts  — SERVER ONLY. Never import this from a client component.
const BASE = process.env.MYNDY_API_BASE ?? "https://hello.myndy.ai/api/public/v1";
const KEY = process.env.MYNDY_API_KEY;

if (!KEY) throw new Error("MYNDY_API_KEY is not set");

type Query = Record<string, string | number | boolean | undefined>;

async function request<T>(path: string, init: RequestInit = {}, query?: Query): Promise<T> {
  const url = new URL(BASE + path);
  for (const [k, v] of Object.entries(query ?? {})) {
    if (v !== undefined) url.searchParams.set(k, String(v));
  }

  const res = await fetch(url, {
    ...init,
    headers: {
      "X-API-Key": KEY!,
      "Content-Type": "application/json",
      ...init.headers,
    },
    cache: "no-store",
  });

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("retry-after") ?? 60);
    throw new Error(`Rate limited. Retry after ${retryAfter}s`);
  }

  if (!res.ok) {
    const detail = await res.text();
    throw new Error(`Myndy ${res.status}: ${detail}`);
  }

  return res.json() as Promise<T>;
}

// Path segments containing "+" must be encoded.
const num = (phone: string) => encodeURIComponent(phone);

export const myndy = {
  me: () => request<any>("/me"),
  numbers: () => request<any>("/numbers"),

  listConversations: (q?: Query) => request<any>("/conversations", {}, q),
  getThread: (phone: string, q?: Query) =>
    request<any>(`/conversations/${num(phone)}`, {}, q),
  markAllRead: () => request<any>("/conversations/mark-all-read", { method: "POST" }),

  sendMessage: (body: { to: string; body?: string; from_number?: string; media_urls?: string[] }) =>
    request<any>("/messages", { method: "POST", body: JSON.stringify(body) }),

  listCalls: (q?: Query) => request<any>("/calls", {}, q),
  history: (q?: Query) => request<any>("/history", {}, q),
  voiceToken: (q?: Query) => request<any>("/calls/voice-token", {}, q),
  dial: (to: string, from_number?: string) =>
    request<any>("/calls/dial", { method: "POST", body: JSON.stringify({ to, from_number }) }),

  listContacts: (q?: Query) => request<any>("/contacts", {}, q),
  createContact: (contact: Record<string, unknown>) =>
    request<any>("/contacts", { method: "POST", body: JSON.stringify(contact) }),
  updateContact: (id: string, patch: Record<string, unknown>) =>
    request<any>(`/contacts/${id}`, { method: "PUT", body: JSON.stringify(patch) }),
  deleteContact: (id: string) => request<any>(`/contacts/${id}`, { method: "DELETE" }),
};

// app/api/myndy/conversations/route.ts
import { myndy } from "@/lib/myndy";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);

  const data = await myndy.listConversations({
    limit: Number(searchParams.get("limit") ?? 25),
    cursor: searchParams.get("cursor") ?? undefined,
    activity_filter: searchParams.get("filter") ?? undefined,
  });

  return Response.json(data);
}

# Server-side only. None of these may be prefixed NEXT_PUBLIC_.
MYNDY_API_KEY=myndy_your_key_here
MYNDY_API_BASE=https://hello.myndy.ai/api/public/v1
MYNDY_WEBHOOK_SECRET=myndy_wh-from_the_tools_page