{"openapi":"3.1.0","info":{"title":"smarttalkapp Public API","version":"1.0.0","description":"WhatsApp inbox + CRM API. Authenticate per channel via Bearer token issued from Settings → WhatsApp → Generate API token.","contact":{"name":"smarttalkapp Developer Support","url":"https://www.smarttalkapp.com/docs/api"}},"servers":[{"url":"https://www.smarttalkapp.com/api/v1","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"stk_<hex>","description":"Channel public API token. Header: `Authorization: Bearer stk_xxx`"}},"schemas":{"SendTextRequest":{"type":"object","required":["to","text"],"properties":{"to":{"type":"string","description":"E.164 phone number, digits only (e.g. 573108760539)"},"text":{"type":"string","maxLength":4096},"contact_name":{"type":"string","description":"Display name for auto-created contacts"},"channel_id":{"type":"integer","description":"Optional respond.io channel id (legacy compat)"}}},"SendTemplateRequest":{"type":"object","required":["to","name","language"],"properties":{"to":{"type":"string"},"name":{"type":"string","description":"Template name as approved in Meta Business Manager"},"language":{"type":"string","default":"es_CO"},"body_params":{"type":"array","items":{"type":"string"}},"contact_name":{"type":"string"},"channel_id":{"type":"integer"}}},"SendMediaRequest":{"type":"object","required":["to","type","media_url"],"properties":{"to":{"type":"string"},"type":{"type":"string","enum":["image","video","audio","document"]},"media_url":{"type":"string","format":"uri"},"caption":{"type":"string"},"filename":{"type":"string"},"contact_name":{"type":"string"},"channel_id":{"type":"integer"}}},"MessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"message_id":{"type":"string","format":"uuid"},"wa_message_id":{"type":"string","description":"Meta wamid","nullable":true},"conversation_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["sent"]},"sent_at":{"type":"string","format":"date-time"}}},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","invalid_request","not_found","conflict","provider_error","internal_error"]},"message":{"type":"string"},"meta":{"type":"object","additionalProperties":true}}},"request_id":{"type":"string"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"wa_id":{"type":"string"},"name":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"last_message_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WebhookEvent":{"type":"object","properties":{"event":{"type":"string","enum":["message.incoming","message.outgoing","message.status","contact.created","contact.updated","conversation.opened","conversation.closed","conversation.assignee_updated"]},"delivery_id":{"type":"string","format":"uuid"},"occurred_at":{"type":"string","format":"date-time"},"channel_id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true}}}}},"paths":{"/health":{"get":{"summary":"Liveness check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"version":{"type":"string"},"deployment":{"type":"string"},"channels_active":{"type":"integer"},"now":{"type":"string","format":"date-time"}}}}}}}}},"/messages/text":{"post":{"summary":"Send a text message","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTextRequest"}}}},"parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string","format":"uuid"},"description":"UUID for safe retries (24h TTL)."}],"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"outside_24h_window — use template instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"invalid_recipient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/messages/template":{"post":{"summary":"Send a pre-approved template message (works outside 24h window)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTemplateRequest"}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"422":{"description":"template_disapproved or paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/messages/media":{"post":{"summary":"Send media (image, video, audio, document) — renders natively in WhatsApp","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMediaRequest"}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"413":{"description":"media_too_large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/messages/recent":{"get":{"summary":"List recent messages on this channel","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object"}}}}}}}}}},"/contacts/{contact_id}":{"get":{"summary":"Get contact by id","parameters":[{"in":"path","name":"contact_id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"description":"not_found"}}}},"/contacts/by-phone/{phone}":{"get":{"summary":"Find contact by phone (digits only, E.164 without +)","parameters":[{"in":"path","name":"phone","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"description":"not_found"}}}}}}