{ "openapi": "3.1.0", "info": { "title": "Mesajilet Developer API", "version": "1.0.0", "description": "Kanal-bağımsız mesajlaşma API'si (WhatsApp, Instagram DM, Messenger, Web). Her hata standart zarf ile döner: code, message, reason, fix, request_id.", "contact": { "name": "Mesajilet", "url": "https://mesajilet.com" } }, "servers": [ { "url": "https://all.mesajilet.com/api/v1" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Hesap" }, { "name": "Mesajlar" }, { "name": "Şablonlar" }, { "name": "Medya" }, { "name": "Kişiler" }, { "name": "Webhook" } ], "paths": { "/me": { "get": { "tags": [ "Hesap" ], "summary": "Anahtar ve hesap bilgisi (bağlantı testi)", "responses": { "200": { "description": "OK" }, "401": { "description": "Kimlik hatası", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/channels": { "get": { "tags": [ "Hesap" ], "summary": "Kanallar, yetenekler ve bağlantılar", "responses": { "200": { "description": "OK" } } } }, "/messages": { "post": { "tags": [ "Mesajlar" ], "summary": "Serbest (oturum) mesajı gönder", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "responses": { "202": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "409": { "description": "Pencere kapalı / bağlantı yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Doğrulama", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Hız sınırı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/messages/template": { "get": { "tags": [ "Mesajlar" ], "summary": "Şablon gönder (tek URL)", "description": "POST /messages/template ile aynı işlem; başlık/gövde kuramayan çağırıcılar için. Aynı istek 60 sn içinde tekrarlanırsa mesaj yeniden gönderilmez.", "parameters": [ { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "example": "905321234567" }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "example": "kargo_cikti" }, { "name": "var1", "in": "query", "description": "Sıralı değişken (var1, var2, …). İsimli şablonda vars[ad]=…", "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Genelde gerekmez; şablon adından çözülür.", "schema": { "type": "string" } }, { "name": "connection_id", "in": "query", "schema": { "type": "string" } }, { "name": "idempotency_key", "in": "query", "description": "Verilirse tekrar koruması 24 saate çıkar.", "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "description": "Yalnız bu uçta geçerli. Başlık kurabiliyorsanız Authorization kullanın.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "404": { "description": "Şablon yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Doğrulama", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Mesajlar" ], "summary": "Onaylı şablon gönder (WhatsApp)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTemplate" } } } }, "responses": { "202": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "404": { "description": "Şablon yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Değişken/onay hatası", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/messages/template/{api_key}": { "get": { "tags": [ "Mesajlar" ], "summary": "Şablon gönder (anahtar adreste)", "description": "GET /messages/template ile aynı; API anahtarı adres yolunda taşınır — başlık da sorgu da kuramayan çağırıcılar için.", "parameters": [ { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "msj_live_…" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "example": "905321234567" }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "example": "kargo_cikti" }, { "name": "var1", "in": "query", "description": "Sıralı değişken (var1, var2, …). İsimli şablonda vars[ad]=…", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "401": { "description": "Anahtar geçersiz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Şablon yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/messages/{id}": { "get": { "tags": [ "Mesajlar" ], "summary": "Mesaj durumu", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "msg_1724412345678" } ], "responses": { "200": { "description": "Mesaj kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "404": { "description": "Bulunamadı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/templates": { "get": { "tags": [ "Şablonlar" ], "summary": "Şablon listesi + değişken şeması", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ] } }, { "name": "language", "in": "query", "schema": { "type": "string" }, "example": "tr" }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ] } } ], "responses": { "200": { "description": "OK" } } } }, "/media": { "post": { "tags": [ "Medya" ], "summary": "Medya yükle → media id (WhatsApp)", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "channel": { "type": "string", "default": "whatsapp" }, "connection_id": { "type": "string" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Yüklendi" }, "413": { "description": "Çok büyük", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Tür desteklenmiyor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/contacts/{id}/window": { "get": { "tags": [ "Kişiler" ], "summary": "Serbest mesaj penceresi açık mı", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "schema": { "type": "string", "default": "whatsapp" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhooks/test": { "post": { "tags": [ "Webhook" ], "summary": "Tanımlı webhook adresine örnek olay gönder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message.received", "message.status", "template.status" ] } } } } } }, "responses": { "200": { "description": "Teslim edildi" }, "409": { "description": "Webhook tanımsız", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Ulaşılamadı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/conversations": { "get": { "tags": [ "Sohbetler" ], "summary": "Sohbet listesi", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "bot" ] } }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "whatsapp", "instagram", "messenger", "web" ] } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } }, { "name": "unread", "in": "query", "schema": { "type": "boolean" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Yetkisiz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Kapsam yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/conversations/{phone}": { "get": { "tags": [ "Sohbetler" ], "summary": "Sohbet detayi", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Sohbet yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Sohbetler" ], "summary": "Sohbeti kapat/ac veya temsilciye ata", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] }, "agent_id": { "type": "integer", "nullable": true }, "unread_count": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK" }, "404": { "description": "Sohbet yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Dogrulama", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/conversations/{phone}/messages": { "get": { "tags": [ "Sohbetler" ], "summary": "Mesaj gecmisi", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 50 } }, { "name": "before", "in": "query", "description": "ISO zaman damgasi - sayfalama imleci", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "in", "out" ] } } ], "responses": { "200": { "description": "OK" } } } }, "/contacts": { "get": { "tags": [ "Kişiler" ], "summary": "Kisi listesi", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Kişiler" ], "summary": "Kisi olustur veya guncelle (upsert)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "username": { "type": "string" } } } } } }, "responses": { "200": { "description": "Guncellendi" }, "201": { "description": "Olusturuldu" } } } }, "/contacts/{phone}": { "get": { "tags": [ "Kişiler" ], "summary": "Kisi detayi (opt-out ve engel durumu dahil)", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Kisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Kişiler" ], "summary": "Kisi guncelle", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Kisi yok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/opt-outs": { "get": { "tags": [ "Kişiler" ], "summary": "Pazarlama cikis listesi", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Kişiler" ], "summary": "Pazarlama cikisina ekle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "source": { "type": "string" } } } } } }, "responses": { "201": { "description": "Eklendi" } } } }, "/opt-outs/{phone}": { "delete": { "tags": [ "Kişiler" ], "summary": "Pazarlama cikisindan cikar - kisi yeniden pazarlama mesaji almaya baslar", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/blocked-numbers": { "get": { "tags": [ "Kişiler" ], "summary": "Engellenen numaralar", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "Kişiler" ], "summary": "Numara engelle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "201": { "description": "Engellendi" } } } }, "/blocked-numbers/{phone}": { "delete": { "tags": [ "Kişiler" ], "summary": "Engeli kaldir", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/stats": { "get": { "tags": [ "Raporlar" ], "summary": "Donem ozeti (mesaj, teslim, okunma, sohbet)", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" } } } }, "/labels": { "get": { "tags": [ "Raporlar" ], "summary": "Etiketler", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } } ], "responses": { "200": { "description": "OK" } } } }, "/agents": { "get": { "tags": [ "Raporlar" ], "summary": "Temsilciler", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Onceki yanittaki pagination.next_cursor", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "msj_live_…" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Aynı isteği güvenle tekrarlamak için benzersiz anahtar (24 saat)." } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "API_KEY_REVOKED", "IP_NOT_ALLOWED", "SCOPE_DENIED", "MODULE_DISABLED", "WEBHOOK_MODULE_DISABLED", "ACCOUNT_INACTIVE", "LICENSE_EXPIRED", "RATE_LIMITED", "IDEMPOTENCY_CONFLICT", "INVALID_JSON", "VALIDATION_FAILED", "PAYLOAD_TOO_LARGE", "CHANNEL_UNSUPPORTED", "CHANNEL_NOT_CONNECTED", "CONNECTION_NOT_FOUND", "CHANNEL_FEATURE_UNSUPPORTED", "RECIPIENT_INVALID", "RECIPIENT_BLOCKED", "RECIPIENT_OPTED_OUT", "WINDOW_CLOSED", "WINDOW_NEVER_OPENED", "TEMPLATE_NOT_FOUND", "TEMPLATE_NOT_APPROVED", "TEMPLATE_VARIABLES_MISSING", "TEMPLATE_VARIABLES_FORMAT", "TEMPLATE_HEADER_MISSING", "TEMPLATE_BUTTON_PARAM_MISSING", "MEDIA_REQUIRED", "MEDIA_TOO_LARGE", "MEDIA_TYPE_UNSUPPORTED", "MEDIA_URL_INVALID", "MEDIA_UPLOAD_FAILED", "MESSAGE_NOT_FOUND", "WEBHOOK_NOT_CONFIGURED", "WEBHOOK_URL_INVALID", "WEBHOOK_UNREACHABLE", "PROVIDER_REJECTED", "PROVIDER_UNAVAILABLE", "NOT_FOUND", "METHOD_NOT_ALLOWED", "INTERNAL_ERROR" ] }, "http": { "type": "integer" }, "message": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" }, "param": { "type": "string" }, "errors": { "type": "object" }, "meta_error": { "type": "object" }, "docs": { "type": "string" }, "request_id": { "type": "string" } } } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_1724412345678" }, "channel": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "read", "failed" ] }, "external_id": { "type": "string", "nullable": true }, "text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": "object", "nullable": true } } }, "MessageEnvelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Message" }, "request_id": { "type": "string" } } }, "SendMessage": { "type": "object", "required": [ "to" ], "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "instagram", "messenger", "web" ], "default": "whatsapp" }, "connection_id": { "type": "string", "example": "wa_15" }, "to": { "type": "string", "example": "905321234567" }, "type": { "type": "string", "enum": [ "text", "image", "video", "audio", "document", "location", "interactive" ], "default": "text" }, "text": { "type": "string" }, "preview_url": { "type": "boolean" }, "media": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "caption": { "type": "string" }, "filename": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "address": { "type": "string" }, "interactive": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "button", "list" ] }, "text": { "type": "string" }, "header": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } } }, "button": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object" } } } }, "reply_to": { "type": "string" } } }, "SendTemplate": { "type": "object", "required": [ "to", "name" ], "properties": { "channel": { "type": "string", "default": "whatsapp" }, "connection_id": { "type": "string" }, "to": { "type": "string" }, "name": { "type": "string", "example": "siparis_bilgi" }, "language": { "type": "string", "description": "Genelde gerekmez; dil şablon adından çözülür. Yalnız aynı ad birden çok dilde kayıtlıysa zorunludur." }, "variables": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "POSITIONAL şablonda dizi, NAMED şablonda nesne" }, "header": { "type": "object", "properties": { "media_id": { "type": "string" }, "url": { "type": "string" }, "filename": { "type": "string" }, "text": { "type": "string" } } }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "text": { "type": "string" } } } } } } } } }