Convers8 Developers

Appearance

Contacts Management ​

Convers8 provides a set of API endpoints to manage your WhatsApp contacts. This guide covers how to list, retrieve, and create contacts using the Convers8 API.

Authentication ​

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL ​

https://waba-v1.convers8.africa

Endpoints ​

List Contacts ​

Retrieve a list of all your contacts.

Endpoint: GET /contacts

Example:

bash
curl --request GET \
     --url https://waba-v1.convers8.africa/contacts \
     --header 'Authorization: Bearer YOUR_API_KEY'

Response:

json
{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "contact_20250411ABC",
        "name": "John Doe",
        "phone_number": "1234567890",
        "created_at": "2025-04-11T10:30:00Z",
        "updated_at": "2025-04-11T10:30:00Z"
      },
      {
        "id": "contact_20250411XYZ",
        "name": "Jane Smith",
        "phone_number": "9876543210",
        "created_at": "2025-04-11T11:45:00Z",
        "updated_at": "2025-04-11T11:45:00Z"
      }
    ],
    "pagination": {
      "total": 2,
      "page": 1,
      "per_page": 10,
      "total_pages": 1
    }
  }
}

Get Contact ​

Retrieve a specific contact by ID.

Endpoint: GET /contacts/{contact_id}

Example:

bash
curl --request GET \
     --url https://waba-v1.convers8.africa/contacts/contact_20250411ABC \
     --header 'Authorization: Bearer YOUR_API_KEY'

Response:

json
{
  "success": true,
  "data": {
    "contact": {
      "id": "contact_20250411ABC",
      "name": "John Doe",
      "phone_number": "1234567890",
      "created_at": "2025-04-11T10:30:00Z",
      "updated_at": "2025-04-11T10:30:00Z"
    }
  }
}

Create Contact ​

Create a new contact.

Endpoint: POST /contacts

Request Body:

json
{
  "name": "New Contact",
  "phone_number": "1234567890"
}

Example:

bash
curl --request POST \
     --url https://waba-v1.convers8.africa/contacts \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "New Contact",
       "phone_number": "1234567890"
     }'

Response:

json
{
  "success": true,
  "message": "Contact created successfully",
  "data": {
    "contact": {
      "id": "contact_20250411DEF",
      "name": "New Contact",
      "phone_number": "1234567890",
      "created_at": "2025-04-11T14:20:00Z",
      "updated_at": "2025-04-11T14:20:00Z"
    }
  }
}

Error Handling ​

In case of an error, the API will return a JSON response with an error message:

json
{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "error_code",
    "details": "Error details"
  }
}

Common error codes include:

  • not_found: The requested resource was not found
  • validation_error: The request data failed validation
  • unauthorized: Invalid or missing API key
  • rate_limit_exceeded: Too many requests in a short period

Best Practices ​

  1. Pagination: When listing contacts, use pagination parameters to manage large datasets.
  2. Phone Number Format: Always use the international format for phone numbers (e.g., +1234567890).
  3. Error Handling: Implement proper error handling in your application to manage API errors gracefully.
  4. Rate Limiting: Be mindful of rate limits to avoid being temporarily blocked from the API.