Get API Request Logs

This endpoint retrieves logs of API requests with various filtering options.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/api-requests

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Query Parameters

Example Request

GET /external/api-requests?page=3&limit=10&sent=true&read=false
    &template_name=location&message_uid=6a7d01ee8de8488a
    &start_date=2025-07-02&end_date=2025-07-02

x-api-key: your_api_key_here

Response (200 OK)

{
  "code": 200,
  "message": "API logs fetched successfully",
  "success": true,
  "data": {
    "totalMessages": 10,
    "sentCount": 0,
    "deliveredCount": 0,
    "readCount": 0,
    "failedCount": 0,
    "logs": [
      {
        "template_name": "hello_world",
        "message_uid": "583e40b0c04347c7",
        "contact_number": "+919xxxxxxxxxx",
        "contact_name": "John Doe",
        "sent": null,
        "delivered": null,
        "read": null,
        "failed": null,
        "createdAt": "2025-07-02T04:25:49.001Z"
      }
      // ... more log entries
    ],
    "paginationDetails": {
      "totalCount": 64,
      "totalPages": 7,
      "currentPage": 1,
      "nextPage": 2,
      "prevPage": null
    }
  }
}

Response Fields

Data Object:

• totalMessages (integer): Total number of messages matching the filter criteria.

• sentCount (integer): Number of sent messages.

• deliveredCount (integer): Number of delivered messages.

• readCount (integer): Number of read messages.

• failedCount (integer): Number of failed messages.

• logs (array): Array of log objects.

• paginationDetails (object): Pagination information.

Log Object:

• template_name (string): Name of the template used.

• message_uid (string): Unique identifier for the message.

• contact_number (string/null): Contact number of the recipient.

• contact_name (string/null): Contact name of the recipient.

• sent (boolean/null): Whether the message was sent.

• delivered (boolean/null): Whether the message was delivered.

• read (boolean/null): Whether the message was read.

• failed (boolean/null): Whether the message failed.

• createdAt (string): ISO 8601 timestamp of creation.

Pagination Details:

• totalCount (integer): Total number of items.

• totalPages (integer): Total number of pages.

• currentPage (integer): Current page number.

• nextPage (integer/null): Next page number, null if on last page.

• prevPage (integer/null): Previous page number, null if on first page.

Error Responses

401 Unauthorized

Missing or invalid API key.

400 Bad Request

Invalid query parameters.

Notes:

• All date filters are inclusive.

• Boolean filters (sent, read) should be passed as true or false.

• The response is paginated with a default of 10 items per page.

Get Conversations API

This endpoint retrieves a list of conversations with filtering and pagination options.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/conversations

Authentication

• x-api-key (required): Your API key for authentication.

• Authorization (required): Bearer token in the format: Authorization: Bearer <your_token>

Query Parameters

Example Request

GET /external/conversations?page=1&limit=10&message_direction=incoming

x-api-key: your_api_key_here
Authorization: Bearer your_token_here

Response (200 OK)

{
  "chats": [
    {
      "_id": "6501a1c2f1e4b2001a9b1234",
      "convoId": "65019f9ef1e4b2001a9b5678",
      "contactId": "65019f9ef1e4b2001a9b9999",
      "contactName": "Rahul Sharma",
      "contactNumber": 9876541230,
      "message_direction": "incoming",
      "message_body": "Hello, is the order ready?",
      "message_type": "text",
      "media_url": null,
      "createdAt": "2025-08-25T10:15:30.000Z",
      "updatedAt": "2025-09-01T08:20:10.000Z"
    }
    // ... more entries
  ],
  "totalCount": 4,
  "totalPages": 1,
  "currentPage": 1,
  "nextPage": null,
  "prevPage": null
}

Response Fields

Root Object:

• chats (array): List of conversations.

• totalCount (integer): Total number of conversations matching filters.

• totalPages (integer): Total number of pages available.

• currentPage (integer): Current page number.

• nextPage (integer/null): Next page number, null if none.

• prevPage (integer/null): Previous page number, null if none.

Conversation Object:

• _id (string): Conversation ID.

• convoId (string): Same as _id, represents the conversation identifier.

• contactId (string): Unique contact identifier.

• contactName (string): Name of the contact.

• contactNumber (number): Contact’s phone number.

• message_direction (string): Direction of the message (incoming or outgoing).

• message_body (string): Content of the message.

• message_type (string): Type of message (text, file, etc.).

• media_url (string): URL of the media file (if any).

• createdAt (string): ISO 8601 timestamp when message was created.

• updatedAt (string): ISO 8601 timestamp when message was last updated.

Error Responses

401 Unauthorized

{
  "code": 401,
  "message": "Missing or invalid API key or token",
  "success": false
}

400 Bad Request

{
  "code": 400,
  "message": "Invalid query parameters",
  "success": false
}

Notes:

• All date filters are inclusive.

• Pagination defaults: page=1, limit=10.

• Conversations are sorted by updatedAt (latest first).

Get Incoming Messages

This endpoint retrieves the messages your contacts have sent you (inbound messages only).

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/incoming-messages

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Query Parameters

Example Request

GET /external/incoming-messages?page=1&limit=10&start_date=2025-07-01&end_date=2025-07-31

x-api-key: your_api_key_here
Authorization: Bearer your_token_here

Response (200 OK)

Returns a list of incoming message records. If no messages match the filters, the message field explains that nothing was found and data is an empty list.

Notes

• Use this endpoint when you only care about what contacts have sent you (for example, to sync replies into your own CRM), as opposed to Get Conversations which returns both directions.

Get Recent Chat Messages

This endpoint retrieves recent chat messages (both incoming and outgoing) for your account, one entry per message.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/chat-messages

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Query Parameters

Example Request

GET /external/chat-messages?page=1&limit=20&start_date=2025-08-01&end_date=2025-08-15

x-api-key: your_api_key_here
Authorization: Bearer your_token_here

Error Responses

400 Bad Request

Returned if:

• limit is higher than the maximum allowed page size.

• The gap between start_date and end_date is more than 30 days.

{
  "code": 400,
  "success": false,
  "message": "Date range cannot exceed 30days"
}

Notes

• The date range for this endpoint cannot span more than 30 days at a time — for a longer history, make multiple requests covering different 30-day windows.

Add or Remove Tags on Contacts

These two endpoints let you apply or remove a WappCloud contact tag on one or more contacts at once — useful for keeping your contact segments in sync when a lead’s status changes in your own system (e.g., tagging someone “customer” after they complete a purchase on your website).

Add a Tag

POST https://client-api.wappcloud.com/api/v1/external/contacts/add-tags

Remove a Tag

DELETE https://client-api.wappcloud.com/api/v1/external/contacts/remove-tags

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Request Body

{
  "contactIds": ["65019f9ef1e4b2001a9b9999", "65019f9ef1e4b2001a9b8888"],
  "userTagName": "vip-customer"
}

Response (Success)

{
  "code": 200,
  "success": true,
  "message": "Tag added to contacts successfully"
}

Error Responses

400 Bad Request

Returned when userTagName is missing, or contactIds is missing/empty.

{
  "code": 400,
  "success": false,
  "message": "At least one contact ID is required"
}

Notes

• Tag names are not case-sensitive — they are stored in lowercase automatically.

• You need the WappCloud contact IDs to use this endpoint (for example, from Get Conversations or from your own records of contacts previously synced from WappCloud).

Get API Usage Summary

Returns how many API requests you have made this calendar month against your plan’s monthly limit, plus any prepaid top-up credit balance.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/api-usage-summary

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "planName": "growth",
    "monthlyLimit": 10000,
    "used": 2450,
    "getRequestCount": 1200,
    "postRequestCount": 1250,
    "remaining": 7550,
    "month": "2026-09",
    "creditUsage": null
  }
}

Notes

• Only requests that create or change something (for example sending a message or creating a template) count against your monthly limit. Read-only requests like fetching logs or conversations do not.

Get API Usage History

Returns your API usage broken down by month for the current calendar year, most recent month first — useful for tracking usage trends over time.

Endpoint

GET https://client-api.wappcloud.com/api/v1/external/api-usage-history

Authentication

• x-api-key (required) — Your API key for authentication.

• Authorization (required) — Bearer token for authentication. Format: Bearer <your_token>

Response (200 OK)

{
  "success": true,
  "message": "API usage history fetched successfully",
  "data": [
    {
      "month": "2026-09",
      "getRequestCount": 1200,
      "postRequestCount": 1250,
      "requestCount": 2450,
      "lastUsed": "2026-09-04T09:12:00.000Z"
    },
    {
      "month": "2026-08",
      "getRequestCount": 900,
      "postRequestCount": 1100,
      "requestCount": 2000,
      "lastUsed": "2026-08-30T18:45:00.000Z"
    }
  ]
}