Dokumentacja Chat API

Uwierzytelnianie

Każde żądanie jest uwierzytelniane kluczem API Twojej przestrzeni roboczej, przesyłanym w nagłówku X-API-Key (lub jako parametr api_key). Klucze wyglądają tak: ck_live_.... Traktuj klucz jak hasło - każdy, kto go posiada, może wysyłać wiadomości obciążające Twoją przestrzeń roboczą. Rotuj go w dowolnej chwili w Ustawienia -> Dostęp do API; poprzedni klucz przestaje działać natychmiast.

Wyślij wiadomość

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parametry:

• message (ciąg znaków) - wiadomość odwiedzającego. Wymagane, chyba że dołączono files.
• ticket_id (ciąg znaków, opcjonalny) - kontynuuj istniejącą rozmowę. Pomiń, aby rozpocząć nową.
• visitor_email / visitor_name (ciąg znaków, opcjonalny) - dołącz dane kontaktowe do zgłoszenia.
• files (multipart, opcjonalny) - załączniki odwiedzającego. Wymaga planu z przesyłaniem plików.

Odpowiedź

Wywołanie zwraca 202 Accepted, gdy tylko wiadomość zostanie zapisana; odpowiedź AI jest generowana asynchronicznie.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Przekaż data.ticket_id jako ticket_id w kolejnym wywołaniu, aby kontynuować rozmowę. Aby otrzymać odpowiedź AI, zasubskrybuj przez WebSocket (ActionCable) kanał identyfikowany przez data.id - ten sam hash odwiedzającego, którego używa osadzony widget.

Odczytywanie rozmów

Pobieraj zgłoszenia i ich wiadomości przy użyciu tego samego klucza X-API-Key. Każdy endpoint odczytu jest ograniczony do Twojej przestrzeni roboczej i dostępny w planie Business.

• GET /api/v1/chat/tickets - lista zgłoszeń, od najnowszych. Parametry zapytania: status, limit (maks. 100), offset. Zwraca tickets oraz pagination.
• GET /api/v1/chat/tickets/:id - pojedyncze zgłoszenie.
• GET /api/v1/chat/tickets/:id/messages - wiadomości zgłoszenia w kolejności, każda z polami role, content i attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Limity żądań i kwota

Żądania są ograniczane do około 20 na minutę na klucz (oraz na IP). Każda wygenerowana odpowiedź pobiera również z miesięcznego limitu wiadomości Twojego planu; po jego wyczerpaniu endpoint zwraca 200 z data.limit_reached: true zamiast generować odpowiedź.

Błędy

• 401 - nie podano klucza API.
• 404 - klucz nie pasuje do żadnej przestrzeni roboczej (np. po rotacji).
• 403 plan_upgrade_required - przestrzeń robocza nie jest w planie Business.
• 403 - subskrypcja jest nieaktywna lub żądanie pochodzi z domeny niedozwolonej przez ustawienia widgetu.
• 422 - brakuje wiadomości (i nie dołączono żadnych plików).