{ "components": { "parameters": {}, "schemas": { "ApiError": { "properties": { "error": { "properties": { "code": { "description": "Machine-readable error code.", "example": "VALIDATION_ERROR", "type": "string" }, "details": { "additionalProperties": {}, "description": "Additional error context (e.g. field-level validation errors).", "type": "object" }, "message": { "description": "Human-readable error message.", "example": "Invalid request parameters", "type": "string" }, "request_id": { "description": "Request identifier for support/debugging.", "example": "req_abc123", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Conversation": { "properties": { "agent_id": { "format": "uuid", "type": [ "string", "null" ] }, "assigned_user_id": { "format": "uuid", "type": [ "string", "null" ] }, "company_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "customer_id": { "format": "uuid", "type": "string" }, "details": { "additionalProperties": {}, "type": [ "object", "null" ] }, "external_conversation_id": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "integration_id": { "format": "uuid", "type": [ "string", "null" ] }, "last_message_at": { "format": "date-time", "type": [ "string", "null" ] }, "provider": { "description": "Messaging provider (e.g. `whatsapp`).", "type": "string" }, "session_id": { "type": [ "string", "null" ] }, "status": { "description": "Conversation status.", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "watsi_enabled": { "description": "Whether the AI agent is active on this conversation.", "type": "boolean" } }, "required": [ "id", "company_id", "customer_id", "agent_id", "integration_id", "session_id", "provider", "status", "watsi_enabled", "assigned_user_id", "details", "last_message_at", "external_conversation_id", "created_at", "updated_at", "customer" ], "type": "object" }, "ConversationList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Conversation" }, "type": "array" }, "has_more": { "description": "Whether more results are available for pagination.", "type": "boolean" }, "next_cursor": { "description": "Opaque cursor for the next page, or null when exhausted.", "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor", "has_more" ], "type": "object" }, "Customer": { "properties": { "company_id": { "format": "uuid", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "image_url": { "format": "uri", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": {}, "description": "Arbitrary key-value metadata.", "type": [ "object", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone_number": { "description": "E.164 phone number.", "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "wa_id": { "description": "WhatsApp identifier.", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "phone_number", "wa_id", "email", "name", "image_url", "metadata", "created_at", "updated_at" ], "type": "object" }, "CustomerDetail": { "properties": { "company_id": { "format": "uuid", "type": [ "string", "null" ] }, "conversation_count": { "description": "Total number of conversations with this customer.", "type": "integer" }, "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "image_url": { "format": "uri", "type": [ "string", "null" ] }, "last_message_at": { "format": "date-time", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": {}, "description": "Arbitrary key-value metadata.", "type": [ "object", "null" ] }, "name": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "phone_number": { "description": "E.164 phone number.", "type": [ "string", "null" ] }, "profile_name": { "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "updated_at": { "format": "date-time", "type": [ "string", "null" ] }, "wa_id": { "description": "WhatsApp identifier.", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "phone_number", "wa_id", "email", "name", "profile_name", "image_url", "notes", "tags", "metadata", "last_message_at", "created_at", "updated_at", "conversation_count" ], "type": "object" }, "CustomerList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Customer" }, "type": "array" }, "has_more": { "description": "Whether more results are available for pagination.", "type": "boolean" }, "next_cursor": { "description": "Opaque cursor for the next page, or null when exhausted.", "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor", "has_more" ], "type": "object" }, "Health": { "properties": { "service": { "example": "watsi-api", "type": "string" }, "status": { "example": "ok", "type": "string" }, "version": { "example": "dev", "type": "string" } }, "required": [ "status", "service", "version" ], "type": "object" }, "Template": { "properties": { "category": { "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ], "type": "string" }, "components": { "items": { "$ref": "#/components/schemas/TemplateComponent" }, "type": "array" }, "id": { "description": "Meta template identifier.", "type": "string" }, "language": { "description": "BCP 47 language tag (e.g. `en_US`).", "type": "string" }, "name": { "description": "Template name (lowercase, underscores only).", "type": "string" }, "quality_score": { "description": "Meta quality score, if available.", "properties": { "date": { "type": "integer" }, "score": { "type": "string" } }, "required": [ "score", "date" ], "type": "object" }, "rejected_reason": { "description": "Reason for rejection (when status is REJECTED).", "type": "string" }, "status": { "enum": [ "PENDING", "APPROVED", "REJECTED", "PAUSED", "DISABLED" ], "type": "string" } }, "required": [ "id", "name", "status", "category", "language", "components" ], "type": "object" }, "TemplateComponent": { "properties": { "buttons": { "description": "Only present for BUTTONS components.", "items": { "properties": { "phone_number": { "type": "string" }, "text": { "type": "string" }, "type": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "text" ], "type": "object" }, "type": "array" }, "format": { "description": "Only present for HEADER components.", "enum": [ "TEXT", "IMAGE", "VIDEO", "DOCUMENT" ], "type": "string" }, "text": { "description": "Component text content. May contain `{{n}}` placeholders.", "type": "string" }, "type": { "enum": [ "HEADER", "BODY", "FOOTER", "BUTTONS" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "TemplateList": { "properties": { "templates": { "items": { "$ref": "#/components/schemas/Template" }, "type": "array" }, "total": { "description": "Total number of templates returned.", "type": "integer" } }, "required": [ "templates", "total" ], "type": "object" }, "User": { "properties": { "createdAt": { "description": "When the user was created.", "format": "date-time", "type": "string" }, "email": { "description": "Email address.", "format": "email", "type": "string" }, "id": { "description": "Unique user identifier.", "format": "uuid", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "role": { "description": "Workspace role (e.g. `admin`, `member`).", "type": [ "string", "null" ] }, "status": { "description": "Account status.", "enum": [ "active" ], "type": "string" } }, "required": [ "id", "name", "email", "role", "status", "createdAt" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "JWT", "description": "Workspace API key passed as a Bearer token.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "watsi", "url": "https://watsi.ai" }, "description": "API reference for the watsi WhatsApp CRM platform.\n\n## Getting started\n\n### 1. Create an API key\n\nOpen **Settings → API Keys** in the [watsi dashboard](https://app.watsi.ai/settings) and generate a new key.\nCopy the key — it is shown only once.\n\n### 2. Make your first API call\n\n```bash\ncurl https://api.watsi.ai/api/v1/conversations \\\n -H \"Authorization: Bearer ***\"\n```\n\nA successful response returns a JSON object:\n\n```json\n{\n \"chats\": [],\n \"hasMore\": false\n}\n```\n\n### 3. Connect via MCP\n\nwatsi exposes an MCP server so you can interact with your workspace from AI-enabled editors.\n\n#### Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"watsi\": {\n \"url\": \"https://mcp.watsi.ai/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\n#### Cursor\n\nAdd this to your `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"watsi\": {\n \"url\": \"https://mcp.watsi.ai/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\n---\n\n## Response format\n\n### Success envelope\n\nAll list endpoints return a JSON object with the resource array and pagination metadata:\n\n```json\n{\n \"chats\": [ ... ],\n \"hasMore\": true\n}\n```\n\n### Error format\n\nErrors return a JSON object with a human-readable message:\n\n```json\n{\n \"error\": \"Unauthorized\"\n}\n```\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Bad request — check your query parameters |\n| 401 | Unauthorized — missing or invalid API key |\n| 404 | Resource not found |\n| 429 | Rate limited — slow down and retry |\n| 500 | Internal server error |\n\n### Pagination\n\nList endpoints use **cursor-based pagination**. Pass the `before` parameter (ISO 8601 datetime)\nto fetch the next page. The `hasMore` field indicates whether additional pages exist.\n\n```bash\ncurl \"https://api.watsi.ai/api/v1/conversations?limit=20&before=2025-03-15T10:30:00.000Z\" \\\n -H \"Authorization: Bearer ***\"\n```\n\n---\n\n## Rate limiting\n\nThe API allows **100 requests per minute** per API key.\n\nWhen you hit the limit the API returns `429 Too Many Requests` with a `Retry-After` header\nindicating how many seconds to wait before retrying.\n\n```\nHTTP/1.1 429 Too Many Requests\nRetry-After: 30\nContent-Type: application/json\n\n{ \"error\": \"Rate limit exceeded. Retry after 30 seconds.\" }\n```\n\n---\n\n## 24-hour messaging window\n\nWhatsApp enforces a **24-hour customer-service window**. You can only send free-form messages\nto a contact within 24 hours of their last inbound message. Outside this window you must use\na pre-approved **message template**.\n\nThe `last_message_at` field on each conversation tells you when the window expires.", "license": { "name": "Proprietary", "url": "https://watsi.ai/terms" }, "title": "watsi API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/api/v1/contacts": { "get": { "description": "Alias for `GET /api/v1/customers`. Use this route going forward.", "operationId": "listContacts", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Maximum number of customers to return (1–100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Customer ID cursor for pagination. Returns results after this ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Paginated list of customers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "List contacts", "tags": [ "Customers" ] } }, "/api/v1/contacts/search": { "get": { "description": "Alias for `GET /api/v1/customers/search`. Use this route going forward.", "operationId": "searchContacts", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "description": "Search query (matches name, phone number, or email).", "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Maximum number of customers to return (1–100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Customer ID cursor for pagination. Returns results after this ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Paginated list of matching customers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "Search contacts", "tags": [ "Customers" ] } }, "/api/v1/contacts/{id}": { "get": { "description": "Alias for `GET /api/v1/customers/{id}`. Use this route going forward.", "operationId": "getContact", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Customer ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDetail" } } }, "description": "Customer details with conversation summary" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Customer not found." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a contact", "tags": [ "Customers" ] } }, "/api/v1/conversations": { "get": { "description": "Returns a paginated list of conversations for the workspace.\nSupports cursor-based pagination via the `before` parameter and\noptional filtering by status.", "operationId": "listConversations", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "description": "Filter by conversation status.", "enum": [ "active", "closed", "pending" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum number of conversations to return (1–100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "before", "required": false, "schema": { "description": "ISO 8601 datetime cursor. Only conversations with `last_message_at` before this value are returned.", "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationList" } } }, "description": "Paginated list of conversations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." } }, "security": [ { "BearerAuth": [] } ], "summary": "List conversations", "tags": [ "Conversations" ] } }, "/api/v1/customers": { "get": { "deprecated": true, "description": "Returns a paginated list of customers for the workspace.\nSupports cursor-based pagination via the `cursor` parameter.\nRequires the `contacts:read` scope.", "operationId": "listCustomers", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Maximum number of customers to return (1–100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Customer ID cursor for pagination. Returns results after this ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Paginated list of customers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "List customers", "tags": [ "Customers" ] } }, "/api/v1/customers/search": { "get": { "deprecated": true, "description": "Searches customers by name, phone number, or email.\nReturns a paginated list of matching customers.\nRequires the `contacts:read` scope.", "operationId": "searchCustomers", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "description": "Search query (matches name, phone number, or email).", "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Maximum number of customers to return (1–100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Customer ID cursor for pagination. Returns results after this ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Paginated list of matching customers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "Search customers", "tags": [ "Customers" ] } }, "/api/v1/customers/{id}": { "get": { "deprecated": true, "description": "Returns a single customer with a conversation summary.\nRequires the `contacts:read` scope.", "operationId": "getCustomer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Customer ID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDetail" } } }, "description": "Customer details with conversation summary" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Insufficient scope — requires `contacts:read`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Customer not found." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint not yet implemented." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a customer", "tags": [ "Customers" ] } }, "/api/v1/users": { "get": { "description": "Returns every user that belongs to the authenticated workspace.", "operationId": "listUsers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/User" }, "type": "array" } } }, "description": "List of workspace users" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." } }, "security": [ { "BearerAuth": [] } ], "summary": "List workspace users", "tags": [ "Users" ] } }, "/api/v1/whatsapp/templates": { "get": { "description": "Proxies the Meta Graph API to return all message templates\nregistered for the workspace's WhatsApp Business Account.", "operationId": "listWhatsAppTemplates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } }, "description": "List of WhatsApp message templates" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid request parameters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Missing or invalid authentication token." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "WhatsApp integration not found or not connected." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error." } }, "security": [ { "BearerAuth": [] } ], "summary": "List WhatsApp message templates", "tags": [ "WhatsApp Templates" ] } }, "/health": { "get": { "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "Service is healthy" } }, "security": [], "summary": "Health check", "tags": [ "System" ] } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.watsi.ai" }, { "description": "Staging", "url": "https://api.stg.watsi.ai" }, { "description": "Local development", "url": "http://localhost:4001" } ], "tags": [ { "description": "Health and status endpoints", "name": "System" }, { "description": "Workspace user management", "name": "Users" }, { "description": "Conversation listing and filtering", "name": "Conversations" }, { "description": "Customer/contact management", "name": "Customers" }, { "description": "WhatsApp message template management", "name": "WhatsApp Templates" }, { "description": "Send WhatsApp messages", "name": "Messages" }, { "description": "Workspace tag management and contact tagging", "name": "Tags" } ], "webhooks": {}, "x-tagGroups": [ { "name": "Getting started", "tags": [ "System" ] }, { "name": "Core resources", "tags": [ "Users", "Conversations", "Customers", "WhatsApp Templates", "Messages", "Tags" ] } ] }