Skip to content
6 min read

Agent API

Build custom agent frontends or automate conversation management.

Base URL: {WALLIN_URL}/api/agent

All endpoints require Sanctum authentication (see Authentication).

Authentication

POST /login

Obtain a Sanctum token for agent access.

Request:

curl -X POST https://wallin.example/api/agent/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "password": "password",
    "device_name": "Mobile App"
  }'

Parameters:

Field Type Description
email string Agent email address
password string Agent password
device_name string Device identifier (for security logs)

Response (200 OK):

{
  "token": "1|abc123defghijklmnopqrstuvwxyz",
  "user": {
    "id": 1,
    "name": "Agent Name",
    "email": "agent@example.com",
    "agent_role": "agent",
    "availability_status": "offline"
  },
  "vapid_public_key": "BG8n_..."
}

Save the token for subsequent requests.

POST /logout

Revoke the current token.

Request:

curl -X POST https://wallin.example/api/agent/logout \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "message": "Logged out"
}

PUT /availability

Update agent availability status.

Request:

curl -X PUT https://wallin.example/api/agent/availability \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

Parameters:

Field Type Values Description
status string online, offline, away Availability status

Response (200 OK):

{
  "status": "online"
}

Conversations

GET /conversations

List conversations assigned to or visible to the agent.

Request:

curl -X GET "https://wallin.example/api/agent/conversations?status=active&channel=whatsapp&page=1" \
  -H "Authorization: Bearer 1|abc123..."

Query Parameters:

Param Type Description
status string Filter by status: active, pending, resolved
channel string Filter by channel: whatsapp, instagram, messenger
search string Search by customer name or phone
page integer Pagination page (default 1)
per_page integer Results per page (default 50)

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "customer_phone_number": "+201001234567",
      "customer_name": "Ahmad",
      "status": "active",
      "channel": "whatsapp",
      "unread_count": 2,
      "last_message_at": "2024-07-19T10:30:00Z",
      "labels": ["inquiry", "urgent"],
      "assigned_to": 1,
      "window_state": "open"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "total": 48
  }
}

GET /conversations/{id}

Get full conversation details with recent messages.

Request:

curl -X GET https://wallin.example/api/agent/conversations/1 \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "data": {
    "id": 1,
    "customer_phone_number": "+201001234567",
    "customer_name": "Ahmad",
    "status": "active",
    "channel": "whatsapp",
    "assigned_to": 1,
    "assigned_to_name": "Agent Smith",
    "last_message_at": "2024-07-19T10:30:00Z",
    "window_state": "open",
    "window_expires_at": "2024-07-20T10:30:00Z"
  }
}

POST /conversations/{id}/assign-self

Assign conversation to the current agent.

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/assign-self \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "success": true
}

POST /conversations/{id}/assign

Assign conversation to another agent.

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/assign \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 5}'

Parameters:

Field Type Description
agent_id integer ID of the agent to assign to

Response (200 OK):

{
  "success": true
}

POST /conversations/{id}/resolve

Mark conversation as resolved.

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/resolve \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"notes": "Issue resolved - refund processed"}'

Parameters:

Field Type Description
notes string Optional notes on resolution

Response (200 OK):

{
  "success": true
}

Messages

GET /conversations/{id}/messages

List messages in a conversation (newest first, paginated).

Request:

curl -X GET "https://wallin.example/api/agent/conversations/1/messages?page=1&per_page=50" \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "direction": "inbound",
      "message_type": "text",
      "content": {"text": "Hello, I need help"},
      "status": "received",
      "created_at": "2024-07-19T10:30:00Z",
      "from_phone_number": "+201001234567"
    }
  ],
  "meta": {"current_page": 1, "last_page": 3}
}

POST /conversations/{id}/messages/text

Send a text message.

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/messages/text \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! How can I help you today?"}'

Parameters:

Field Type Description
message string Message text

Response (201 Created):

{
  "success": true,
  "message_id": 123,
  "status": "sent"
}

POST /conversations/{id}/messages/template

Send a template message (WhatsApp).

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/messages/template \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 42,
    "variables": ["Ahmad", "ORD-123"]
  }'

Parameters:

Field Type Description
template_id integer Template ID from /api/agent/templates
variables array Values for template variables (in order)

Response (201 Created):

{
  "success": true,
  "message_id": 123
}

POST /conversations/{id}/messages/media

Send media (image, document, audio, video).

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/messages/media \
  -H "Authorization: Bearer 1|abc123..." \
  -F "file=@/path/to/image.jpg" \
  -F "type=image" \
  -F "caption=Check this out"

Form Parameters:

Field Type Description
file file Media file
type string Type: image, document, audio, video
caption string Optional caption

Response (201 Created):

{
  "success": true,
  "message_id": 123
}

POST /conversations/{id}/messages/reaction

Send a reaction to a message (emoji).

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/messages/reaction \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "wamid_abc123",
    "emoji": "👍"
  }'

Parameters:

Field Type Description
message_id string WhatsApp message ID (from received message)
emoji string Emoji reaction

Response (201 Created):

{
  "success": true
}

Templates

GET /templates

List approved templates available for sending.

Request:

curl -X GET https://wallin.example/api/agent/templates \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "hello_world",
      "category": "marketing",
      "language": "en",
      "body_content": "Hello {{1}}, welcome!",
      "variable_count": 1
    }
  ]
}

Labels

GET /labels

List available conversation labels.

Request:

curl -X GET https://wallin.example/api/agent/labels \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "data": [
    {
      "slug": "complaint",
      "name": "Complaint",
      "color": "red"
    }
  ]
}

POST /conversations/{id}/labels

Add a label to a conversation.

Request:

curl -X POST https://wallin.example/api/agent/conversations/1/labels \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"slug": "complaint"}'

Response (200 OK):

{
  "success": true
}

DELETE /conversations/{id}/labels/{slug}

Remove a label from a conversation.

Request:

curl -X DELETE https://wallin.example/api/agent/conversations/1/labels/complaint \
  -H "Authorization: Bearer 1|abc123..."

Response (200 OK):

{
  "success": true
}

Real-time Events

Subscribe to real-time events via WebSockets (Reverb + Laravel Echo).

Auth endpoint:

POST /api/broadcasting/auth
Authorization: Bearer 1|abc123...

Available channels:

  • private-conversations.{id} — Updates for a specific conversation (new messages, status changes)
  • private-agent.{userId} — Agent-specific events (assignment, notifications)

Example JavaScript:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

const echo = new Echo({
  broadcaster: 'reverb',
  key: window.env.REVERB_APP_KEY,
  wsHost: window.env.REVERB_HOST,
  wsPort: window.env.REVERB_PORT,
  wssPort: window.env.REVERB_PORT,
  authEndpoint: '/api/broadcasting/auth',
  auth: {
    headers: {
      Authorization: `Bearer ${token}`
    }
  }
});

// Listen for new messages
echo.private(`conversations.1`).listen('NewMessageReceived', (event) => {
  console.log('New message:', event.message);
});

Rate Limiting

Agent API calls are rate-limited to 100 requests per minute per user.

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Was this page helpful?
Previous ← WhatsApp Messaging API
Next Errors & Limits →

See Wallin on your own channels.

Book a walkthrough — we'll connect a test account and show you the inbox, broadcasts, and automation live.

Request a demo Sign in