API Documentation - WhatsApp Flow for Trello

🚀 Overview

WhatsApp Flow API provides endpoints to manage WhatsApp notifications from your Trello boards. All requests should be made to the base URL with appropriate JSON payloads.

🔒 Secure

HTTPS encryption for all endpoints

⚡ Fast

Response times under 100ms

📱 Reliable

WhatsApp Business API integration

🔄 Real-time

Instant webhook processing

🔗 Base URL

https://trello-whatsapp-worker.incimelih.workers.dev

📡 Endpoints

Status Endpoint

GET /

Returns the service status and basic information.

Response

{
  "status": "ok",
  "service": "Trello-WhatsApp Notification Worker"
}

200 OK

Send Verification Code

POST /api/send-verification

Sends a 6-digit verification code via WhatsApp to the specified phone number.

Request

POST /api/send-verification
Content-Type: application/json

{
  "phoneNumber": "905324722862"
}

Phone Number Format

Include country code (e.g., +1 for USA, +90 for Turkey)
Can include or exclude the + symbol
Examples: 905324722862 or +905324722862

Response (Success)

{
  "success": true,
  "message": "Verification code sent to WhatsApp",
  "phoneNumber": "905324722862"
}

200 OK

Response (Error)

{
  "success": false,
  "message": "Phone number required"
}

400 Bad Request 500 Server Error

Details

Verification code valid for 10 minutes
Code stored in KV with TTL
Rate-limited to 1 code per phone number per 10 minutes

Verify Code

POST /api/verify-code

Verifies the code and marks the phone number as verified.

Request

POST /api/verify-code
Content-Type: application/json

{
  "phoneNumber": "905324722862",
  "code": "123456"
}

Response (Success)

{
  "success": true,
  "message": "Phone number verified",
  "phoneNumber": "905324722862",
  "verified": true
}

200 OK

Response (Error)

{
  "success": false,
  "message": "Invalid or expired code"
}

400 Bad Request

Details

Code must be exactly 6 digits
Code expires after 10 minutes
Verified phone stored for 1 year
Code deleted after verification

Test Integration

POST /api/test

Sends a test WhatsApp message to verify the integration works.

Request

POST /api/test
Content-Type: application/json

{
  "phoneNumber": "905324722862"
}

Response (Success)

{
  "success": true,
  "message": "Test notification sent!",
  "messageId": "wamid.HBgMOTA1MzI0NzIyODYyFQIAERgSRjJFMDUwMzM0NjMyRkI0RUQ1AA=="
}

200 OK

Response (Error)

{
  "success": false,
  "error": "WhatsApp Phone Number ID not configured"
}

400 Bad Request 500 Server Error

Get Configuration

GET /api/config

Retrieves the current user configuration.

Query Parameters

Parameter	Type	Description
`userId`	string	Trello user ID (required)
`boardId`	string	Trello board ID (optional)

Response

{
  "success": true,
  "config": {
    "userId": "user123",
    "phoneNumber": "905324722862",
    "verified": true,
    "boards": [
      {
        "boardId": "board1",
        "boardName": "My Board",
        "enabled": true,
        "events": {
          "cardCreated": true,
          "cardUpdated": true,
          "memberAdded": true
        }
      }
    ]
  }
}

200 OK

Update Configuration

POST /api/config

Updates user configuration for board notifications.

Request

POST /api/config
Content-Type: application/json

{
  "userId": "user123",
  "boardId": "board1",
  "boardName": "My Board",
  "phoneNumber": "905324722862",
  "enabled": true,
  "events": {
    "cardCreated": true,
    "cardUpdated": true,
    "cardArchived": false,
    "memberAdded": true,
    "memberRemoved": true,
    "commentAdded": true,
    "dueDateAdded": true,
    "labelAdded": true,
    "attachmentAdded": true
  }
}

Response

{
  "success": true,
  "message": "Configuration saved",
  "boardId": "board1"
}

200 OK

Webhook Endpoint

POST HEAD /webhook/trello

Receives Trello webhook events. Also handles WhatsApp webhook verification.

Webhook Verification (GET)

GET /webhook/trello?hub.verify_token=TOKEN&hub.challenge=CHALLENGE

Supported Event Types

Card events: createCard, updateCard, deleteCard, archiveCard
List events: createList, updateList, deleteList, archiveList
Board events: updateBoard, addMemberToBoard, removeMemberFromBoard
Card details: addMemberToCard, removeMemberFromCard, addLabelToCard, addAttachmentToCard

200 OK 400 Bad Request

⚠️ Error Handling

Status Code	Description	Example Error
200	Success	`{"success": true}`
400	Bad Request	Missing/invalid parameters
500	Server Error	WhatsApp API error

📋 Data Formats

Phone Numbers

Stored with country code
Format: +[country][number]
Examples: +1234567890, +905324722862
Cleaned to digits only before sending

Timestamps

ISO 8601 format
Example: 2025-12-21T12:00:00Z

IDs

Trello IDs are alphanumeric strings
KV keys format: type_id1_id2

💡 Examples

Example 1: Full Verification Flow

# Step 1: Request code
curl -X POST https://trello-whatsapp-worker.incimelih.workers.dev/api/send-verification \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "905324722862"}'

# Step 2: Verify code (after receiving it)
curl -X POST https://trello-whatsapp-worker.incimelih.workers.dev/api/verify-code \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "905324722862",
    "code": "123456"
  }'

Example 2: Configure Notifications

curl -X POST https://trello-whatsapp-worker.incimelih.workers.dev/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "boardId": "board1",
    "boardName": "My Board",
    "phoneNumber": "905324722862",
    "enabled": true,
    "events": {
      "cardCreated": true,
      "cardUpdated": true,
      "memberAdded": true
    }
  }'

🚦 Rate Limiting

📌 Note:

Verification codes: 1 per phone per 10 minutes
WhatsApp API: 1000+ messages per second (per business account)
No endpoint-level rate limiting currently

🔒 Security

CORS Headers

All endpoints return:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Webhook Verification

WhatsApp: GET request with hub.verify_token
Trello: Signature verification using webhook secret

✅ API Ready

You're all set! Start building with WhatsApp Flow API.