API Reference
Complete route table, request/response formats, authentication, and rate limiting
All Chatify functionality is exposed through a JSON API. The bundled UI uses this same API internally.
Default: http://localhost:8000/api/chatify/v1
The prefix is configurable via CHATIFY_API_PREFIX or config('chatify.api.prefix').
All routes require authentication. The auth mechanism depends on your middleware configuration:
| Mode | Middleware | How to authenticate |
|---|
| Web (session) | web,auth | Browser session cookie |
| API (token) | api,auth:sanctum | Authorization: Bearer {token} header |
See Installation for setup details.
Two rate limiter groups are applied:
| Group | Default | Applied to |
|---|
chatify-messages | 60 req/min per user | Send message, typing, search, forward |
chatify-uploads | 10 req/min per user | Avatar upload, attachment upload, background upload, settings |
See Backend Customization to adjust limits.
Responses use Laravel API Resources for consistent JSON structure:
| Resource | Key fields |
|---|
ConversationResource | id, type, name, description, avatar_url, participants_preview, last_message, unread_count, is_pinned, pin_order |
MessageResource | id, conversation_id, body, attachment, sender, reply_to, forwarded_from, edited_at, created_at |
UserResource | id, name, avatar_url, is_online (email included only if api.expose_email is true) |
ParticipantResource | id, user, role, permissions, last_read_at |
UserSettingsResource | theme, font, color, chat_background, locale |
AttachmentResource | name, type, size, url |
List endpoints return paginated responses using Laravel's cursor or offset pagination:
{
"data": [...],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 20,
"total": 95
},
"links": {
"next": "...",
"prev": null
}
}
| Method | URI | Description | Throttle |
|---|
GET | /translations | Get translations for the current locale | -- |
| Method | URI | Description | Throttle |
|---|
GET | /conversations | List inbox (paginated) | -- |
POST | /conversations/direct | Create or find a direct conversation | -- |
POST | /conversations/group | Create a group conversation | -- |
GET | /conversations/{conversation} | Get a single conversation | -- |
PATCH | /conversations/{conversation} | Update conversation (group info) | -- |
POST | /conversations/{conversation}/avatar | Upload group avatar | chatify-uploads |
DELETE | /conversations/{conversation} | Delete a conversation | -- |
POST | /conversations/{conversation}/hide | Hide from inbox | -- |
POST | /conversations/{conversation}/clear | Clear all messages (saved only) | -- |
POST | /conversations/{conversation}/read | Mark as read | -- |
PATCH | /conversations/{conversation}/pin | Pin or unpin | -- |
PUT | /conversations/pin-order | Reorder pinned conversations | -- |
| Method | URI | Description | Throttle |
|---|
GET | /conversations/{conversation}/messages | List messages (paginated) | chatify-messages |
GET | /conversations/{conversation}/messages/search | Search messages | chatify-messages |
POST | /conversations/{conversation}/messages | Send a message | chatify-messages |
PATCH | /messages/{message} | Edit a message | chatify-messages |
DELETE | /messages/{message} | Delete a message | -- |
POST | /conversations/{conversation}/forward | Forward a message | chatify-messages |
| Method | URI | Description | Throttle |
|---|
POST | /conversations/{conversation}/typing | Send typing indicator | chatify-messages |
| Method | URI | Description | Throttle |
|---|
GET | /conversations/{conversation}/participants | List group participants | -- |
POST | /conversations/{conversation}/participants | Add participants | -- |
PATCH | /conversations/{conversation}/participants/{user} | Update role/permissions | -- |
DELETE | /conversations/{conversation}/participants/{user} | Remove a participant | -- |
POST | /conversations/{conversation}/transfer-ownership | Transfer group ownership | -- |
POST | /conversations/{conversation}/leave | Leave a group | -- |
| Method | URI | Description | Throttle |
|---|
GET | /contacts/search | Search users by name | -- |
| Method | URI | Description | Throttle |
|---|
GET | /favorites | List favorite users | -- |
POST | /favorites/{user} | Toggle favorite status | -- |
| Method | URI | Description | Throttle |
|---|
GET | /blocks | List blocked users | -- |
POST | /blocks/{user} | Block a user | -- |
DELETE | /blocks/{user} | Unblock a user | -- |
| Method | URI | Description | Throttle |
|---|
POST | /presence/heartbeat | Send online heartbeat | -- |
POST | /presence/offline | Mark self as offline | -- |
| Method | URI | Description | Throttle |
|---|
GET | /users/{user} | Get user profile | -- |
| Method | URI | Description | Throttle |
|---|
GET | /settings | Get current user settings | -- |
PATCH | /settings | Update settings (theme, font, color, locale) | chatify-uploads |
POST | /settings/avatar | Upload user avatar | chatify-uploads |
POST | /settings/chat-background | Upload custom chat background | chatify-uploads |
| Method | URI | Description | Throttle |
|---|
GET | /conversations/{conversation}/attachments | List conversation attachments | -- |
GET | /attachments/{filename} | Download an attachment | -- |
| Method | URI | Description | Throttle |
|---|
GET | /link-preview | Fetch Open Graph metadata for a URL | -- |
| Method | URI | Description | Throttle |
|---|
POST | /broadcasting/auth | Authorize a broadcast channel subscription | -- |