API introduction

Welcome to the Wasapia API! Our simple REST API allows you to manage flows and recipients for your WhatsApp automation campaigns.

Base URL

All API requests should be made to:

https://api.wasapia.com/v1

Authentication

The API uses API keys for authentication. Generate your API key from your dashboard.

Using your API key

Include your API key in the X-WASAPIA-API-KEY header:

curl -H "X-WASAPIA-API-KEY: YOUR_API_KEY" \
     https://api.wasapia.com/v1/flows

Getting your API key

1. Log in to your Wasapia dashboard
2. Go to Settings → API Keys
3. Click Generate new key
4. Copy and store your key securely

⚠️ Important: Keep your API key secure and never expose it in client-side code.

Request format

• Use HTTPS for all requests
• Include Content-Type: application/json header for POST/PUT requests
• Send data as JSON in the request body

Response format

All responses are JSON with this structure:

Success response

{
  "success": true,
  "message": "Recipient added successfully",
  "data": {
    "phoneNumber": "+1234567890",
    "status": "pending",
    "variables": {
      "name": "John Doe"
    },
    "metadata": {
      "entryPoint": "api",
      "tags": ["vip"],
      "notes": "Important client",
      "addedViaApi": true
    }
  }
}

Error response

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "msg": "Phone number must be in international format (+1234567890)",
      "param": "phoneNumber",
      "location": "body"
    }
  ]
}

Available endpoints

Get flows

Get all your flows.

GET /v1/flows

Query parameters:

• status (optional) - Filter by flow status
• limit (optional, default: 50) - Number of flows to return

Example:

curl -H "X-WASAPIA-API-KEY: YOUR_API_KEY" \
     https://api.wasapia.com/v1/flows?status=active&limit=10

Response:

{
  "success": true,
  "data": [
    {
      "_id": "flow123",
      "name": "Welcome sequence",
      "description": "New user onboarding flow",
      "status": "active",
      "createdAt": "2024-06-02T10:30:00Z",
      "updatedAt": "2024-06-02T10:30:00Z"
    }
  ]
}

Add recipient to flow

Add a new recipient to a specific flow.

POST /v1/flows/{flowId}/recipients

Request body:

{
  "phoneNumber": "+1234567890",
  "variables": {
    "name": "John Doe",
    "company": "Acme Inc"
  },
  "metadata": {
    "tags": ["vip", "enterprise"],
    "notes": "Important client"
  }
}

Required fields:

• phoneNumber - Must be in international format (+1234567890)

Optional fields:

• variables - Object with custom variables for the recipient
• metadata - Object with additional data
  • tags - Array of strings
  • notes - String with notes

Example:

curl -X POST https://api.wasapia.com/v1/flows/flow123/recipients \
  -H "X-WASAPIA-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+1234567890",
    "variables": {
      "name": "John Doe"
    },
    "metadata": {
      "tags": ["new-customer"],
      "notes": "Signed up today"
    }
  }'

Get flow recipients

Get all recipients for a specific flow.

GET /v1/flows/{flowId}/recipients

Query parameters:

• page (optional, default: 1) - Page number
• limit (optional, default: 50) - Recipients per page
• status (optional) - Filter by recipient status
• search (optional) - Search by phone number

Example:

curl -H "X-WASAPIA-API-KEY: YOUR_API_KEY" \
     "https://api.wasapia.com/v1/flows/flow123/recipients?page=1&limit=20&status=pending"

Response:

{
  "success": true,
  "data": [
    {
      "_id": "recipient123",
      "phoneNumber": "+1234567890",
      "status": "pending",
      "variables": {
        "name": "John Doe"
      },
      "metadata": {
        "entryPoint": "api",
        "tags": ["vip"],
        "notes": "Important client",
        "addedViaApi": true
      },
      "createdAt": "2024-06-02T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

Update recipient

Update an existing recipient in a flow.

PUT /v1/flows/{flowId}/recipients/{recipientId}

Request body (all fields optional):

{
  "phoneNumber": "+1234567890",
  "variables": {
    "name": "Jane Doe"
  },
  "status": "completed",
  "metadata": {
    "tags": ["premium"],
    "notes": "Updated information"
  }
}

Valid status values:

• pending
• in_progress
• completed
• exited
• failed

Error codes

Common errors

Invalid phone number

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "msg": "Phone number must be in international format (+1234567890)",
      "param": "phoneNumber"
    }
  ]
}

Flow not found

{
  "success": false,
  "message": "Flow not found"
}

Duplicate recipient

{
  "success": false,
  "message": "Recipient already exists in this flow",
  "data": {
    "_id": "existing_recipient_id",
    "phoneNumber": "+1234567890"
  }
}

Rate limits

The API has rate limits to ensure service quality:

• 1,500 requests per hour per API key

When you exceed the limit, you'll get a 429 Too Many Requests response.

Ready to start? Get your API key and add your first recipient!