DripTell API documentation

API

ENVIRONMENTProduction

LAYOUTLANGUAGE

DEVELOPER REFERENCE v1

DripTell Workspace API

Build customer communication into your own tools. Use the DripTell REST API to manage contacts and leads, send WhatsApp messages, and work with conversations across your connected channels.

Choose an endpoint on the left. Its parameters appear beside copyable requests and response examples. Examples use sample data; browsing this reference never calls your workspace API.

Base URL: https://app.driptell.com
Format: JSON over HTTPS
Version: v1

Manage API keys OpenAPI specification

YOUR FIRST REQUEST

Start with your workspace.

Verify your API key before building your integration.

cURL

curl --request GET 'https://app.driptell.com/api/v1/verify' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

42 endpoints11 groupsREST API

Authentication

Create a workspace API key in Settings → API keys. Send it in the Authorization header with every authenticated request. Each key is limited to its workspace and granted access.

Use GET /api/v1/verify to check the key. Keep keys on your server and out of browser code, public repositories and shared screenshots.

Core concepts

Use resource UUIDs returned by the API. A contact UUID identifies a customer; a connection UUID identifies a sending WhatsApp number.

Omit connection_uuid to use the workspace default number. An explicit sender must be active and allowed for the API key. Invalid senders fail without falling back to another number.

WhatsApp free-form messages require an open customer service window. Use an approved template when that window is closed. Availability on other channels depends on the connection, plan and provider rules.

Pagination: Check each endpoint. Workspace lists commonly use page and per_page; email lists use a cursor.
Safe retries: Lead capture supports Idempotency-Key. Do not assume every workspace write supports idempotency. Check the endpoint before retrying a send.

Errors and rate limits

Workspace endpoints generally return { success, data } on success and { success: false, error } on failure. The public health endpoint uses its own status response.

Message sending has a per-workspace limit, defaulting to 300 requests per minute. A 429 response provides Retry-After. Lead capture has a separate rate bucket. Respect the returned delay and do not retry validation failures unchanged.

401: Check the key and its workspace.
403 / 404: Check access, plan requirements and resource identifiers.
409 / 422: Resolve the conflict or channel requirement before retrying.
429: Wait for Retry-After before sending another request.

GET

Verify API key

https://app.driptell.com/api/v1/verify

Validate the API key and return the workspace it belongs to.

Use this as a health check to confirm a key is valid and to discover which workspace (organization) it is scoped to. Every other endpoint is automatically scoped to this same workspace.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Error responses 1

401: The Authorization header is missing or the key is invalid/revoked.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/verify' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "valid": true,
    "organization": {
      "id": 1,
      "name": "Example Workspace",
      "identifier": "example-workspace"
    },
    "user": {
      "id": 1,
      "email": "owner@example.com",
      "name": "Account Owner",
      "role": "owner"
    }
  }
}

GET

API health

https://app.driptell.com/api/v1/health

Check that the public API is reachable.

Use this unauthenticated endpoint for uptime checks or connector smoke tests. It does not reveal workspace data.

No authentication required

Headers

Acceptstring: application/json

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/health' \
  --header 'Accept: application/json'

Example response

200

JSON

{
  "ok": true,
  "status": "ok",
  "service": "driptell-v4",
  "timestamp": "2026-07-08T00:00:00.000Z"
}

GET

List contacts

https://app.driptell.com/api/v1/contacts

Paginated list of contacts in the workspace, with optional search.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

searchstring: Filter by name, phone, or email (case-insensitive).
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1–100. Default 25.

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/contacts?search=jane&page=1&per_page=25' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "contacts": [
      {
        "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+971500000000",
        "email": "jane@example.com",
        "is_subscribed": true,
        "is_favorite": false,
        "address": {},
        "metadata": {},
        "created_at": "2026-06-01T09:30:00.000Z",
        "updated_at": "2026-06-10T11:05:00.000Z"
      }
    ],
    "page": 1,
    "per_page": 25
  }
}

POST

Create a contact

https://app.driptell.com/api/v1/contacts

Create a new contact. The phone number is normalized to E.164.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

first_namestringRequired: Contact's first name.
phonestringRequired: Phone number; accepts local/00/+ formats and is normalized to E.164.
last_namestring: Contact's last name.
emailstring: Email address.
addressobject: Free-form address object stored as JSON.
metadataobject: Free-form custom fields stored as JSON.

Body raw (JSON)

JSON body

{
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+971500000000",
  "email": "jane@example.com"
}

Error responses 2

400: first_name is missing, or phone is missing/invalid.
409: A contact with the same phone number already exists.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/contacts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+971500000000",
  "email": "jane@example.com"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "jane@example.com",
      "created_at": "2026-06-16T09:30:00.000Z"
    }
  }
}

GET

Get a contact

https://app.driptell.com/api/v1/contacts/{uuid}

Fetch a single contact by its UUID.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

uuidstringRequired: The contact's UUID (the `uuid` field returned by other calls).

Error responses 1

404: No contact with that UUID exists in the workspace.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "jane@example.com",
      "is_subscribed": true,
      "is_favorite": false,
      "blocked_at": null,
      "address": {},
      "metadata": {},
      "created_at": "2026-06-01T09:30:00.000Z",
      "updated_at": "2026-06-10T11:05:00.000Z"
    }
  }
}

PUT

Update a contact

https://app.driptell.com/api/v1/contacts/{uuid}

Update fields on a contact. Only the fields you send are changed.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

uuidstringRequired: The contact's UUID.

Body parameters

first_namestring: New first name.
last_namestring | null: New last name (send null to clear).
phonestring: New phone; normalized to E.164. Rejected if it collides with another contact.
emailstring | null: New email (send null to clear).
addressobject: Replace the address JSON.
metadataobject: Replace the metadata/custom-fields JSON.

Body raw (JSON)

JSON body

{
  "email": "jane.doe@example.com"
}

Error responses 3

400: The provided phone number is invalid.
404: No contact with that UUID exists.
409: The new phone number belongs to another contact.

Example request

cURL

curl --request PUT 'https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "email": "jane.doe@example.com"
}'

Example response

200

JSON

{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "jane.doe@example.com",
      "updated_at": "2026-06-16T10:00:00.000Z"
    }
  }
}

DELETE

Delete a contact

https://app.driptell.com/api/v1/contacts/{uuid}

Soft-delete a contact. The record is hidden from all subsequent API calls.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

uuidstringRequired: The contact's UUID.

Error responses 1

404: No contact with that UUID exists.

Example request

cURL

curl --request DELETE 'https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "deleted": true
  }
}

POST

Create or update a lead

https://app.driptell.com/api/v1/leads

Create a lead from an external webhook/API payload and optionally upsert its contact.

Use this endpoint for website forms, landing pages, lead ads, or partner systems. The API reuses the DripTell lead pipeline, contact record, WhatsApp conversation, custom lead fields, health scoring, and lead.created/lead.updated webhooks.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Idempotency-Keystring: landing-page-12345
Content-TypestringRequired: application/json

Body parameters

phonestring: Contact phone. Normalized to E.164 and used to find or create the contact.
emailstring: Contact email. Used when phone/contact_uuid is not provided.
contact_uuidstring: Existing contact UUID. Takes precedence over phone/email lookup.
first_namestring: Contact first name.
last_namestring: Contact last name.
titlestring: Lead title. Defaults to the contact phone/email.
sourcestring: Lead source, for example website, api, webhook, shopify, or lead_ad. Default api.
external_source_idstring: External/idempotency id. Also accepted through the Idempotency-Key header.
stage_namestring: Pipeline stage name. Defaults to the workspace default stage.
value_amountnumber: Potential deal value.
value_currencystring: Currency code. Defaults to the workspace currency.
prioritylow | normal | high | urgent: Lead priority. Default normal.
lead_scorenumber: Optional explicit health score, 0-100. Otherwise DripTell computes health.
custom_fieldsobject | array: Map lead custom fields by name or [{ field_id, value }].
create_conversationboolean: Create/open the WhatsApp conversation when the contact has a phone. Default true.
connection_uuidstring: WhatsApp sender to use when create_conversation is true. Omit to use the workspace default number.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "first_name": "Jane",
  "title": "Website enquiry",
  "source": "website",
  "external_source_id": "landing-page-12345",
  "stage_name": "New lead",
  "value_amount": 2500,
  "value_currency": "AED",
  "priority": "high",
  "custom_fields": {
    "budget": "2500 AED",
    "interest": "WhatsApp automation"
  }
}

Things to know

Send the same Idempotency-Key or external_source_id again to receive the original lead instead of creating a duplicate.
When an open lead already exists for the contact, DripTell updates it unless update_existing is false.
Configured outbound webhooks receive lead.created or lead.updated automatically.
When create_conversation is true, an explicit connection_uuid opens the conversation on that sender. An invalid or unauthorized sender is rejected without fallback.

Error responses 2

400: No phone/email/contact_uuid is supplied, the phone is invalid, the value is not numeric, or the contact is blocked.
401: Missing or invalid API key.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/leads' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: landing-page-12345' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "first_name": "Jane",
  "title": "Website enquiry",
  "source": "website",
  "external_source_id": "landing-page-12345",
  "stage_name": "New lead",
  "value_amount": 2500,
  "value_currency": "AED",
  "priority": "high",
  "custom_fields": {
    "budget": "2500 AED",
    "interest": "WhatsApp automation"
  }
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "created": true,
    "connection_uuid": "11112222-3333-4444-8555-666677778888",
    "lead": {
      "id": 128,
      "public_id": "7c34773d-88a0-43c4-8c7a-5c32e0f80213",
      "title": "Website enquiry",
      "source": "website",
      "status": "open",
      "stage": "New lead",
      "lead_health_score": 57,
      "lead_health_status": "active",
      "contact_name": "Jane",
      "phone": "+971500000000",
      "conversation_public_id": "d8e5fc33-37e3-4923-90b0-2d46d7fbf412"
    }
  }
}

GET

List contact groups

https://app.driptell.com/api/v1/contact-groups

All contact groups in the workspace with their member counts.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/contact-groups' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "groups": [
      {
        "uuid": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "name": "VIP customers",
        "description": "High-value accounts",
        "created_at": "2026-05-20T08:00:00.000Z",
        "contacts": 42
      }
    ]
  }
}

POST

Create a contact group

https://app.driptell.com/api/v1/contact-groups

Create a new group that contacts can be organized into.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

namestringRequired: Group name.
descriptionstring: Optional description.

Body raw (JSON)

JSON body

{
  "name": "VIP customers",
  "description": "High-value accounts"
}

Error responses 1

400: name is missing.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/contact-groups' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "name": "VIP customers",
  "description": "High-value accounts"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "group": {
      "uuid": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "name": "VIP customers",
      "description": "High-value accounts",
      "created_at": "2026-06-16T09:30:00.000Z"
    }
  }
}

PUT

Update a contact group

https://app.driptell.com/api/v1/contact-groups/{uuid}

Rename a group or change its description.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

uuidstringRequired: The group's UUID.

Body parameters

namestringRequired: New group name.
descriptionstring: New description (omit/empty to clear).

Body raw (JSON)

JSON body

{
  "name": "VIP"
}

Error responses 2

400: name is missing.
404: No group with that UUID exists.

Example request

cURL

curl --request PUT 'https://app.driptell.com/api/v1/contact-groups/8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "name": "VIP"
}'

Example response

200

JSON

{
  "success": true,
  "data": {
    "updated": true
  }
}

DELETE

Delete a contact group

https://app.driptell.com/api/v1/contact-groups/{uuid}

Soft-delete a group. Members are not deleted, only the grouping.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

uuidstringRequired: The group's UUID.

Error responses 1

404: No group with that UUID exists.

Example request

cURL

curl --request DELETE 'https://app.driptell.com/api/v1/contact-groups/8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "deleted": true
  }
}

POST

Add a contact to a group

https://app.driptell.com/api/v1/contact-groups/{uuid}/contacts

Add an existing workspace contact to a contact group.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

uuidstringRequired: The group's UUID.

Body parameters

contact_uuidstringRequired: The contact's UUID.

Body raw (JSON)

JSON body

{
  "contact_uuid": "11112222-3333-4444-8555-666677778888"
}

Things to know

Adding a contact that is already a member is safe and does not create a duplicate membership.

Error responses 1

404: The contact or group does not exist in this workspace.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/contact-groups/8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d/contacts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "contact_uuid": "11112222-3333-4444-8555-666677778888"
}'

Example response

200

JSON

{
  "success": true,
  "data": {
    "membership": {
      "id": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d:11112222-3333-4444-8555-666677778888",
      "group_uuid": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "group_name": "VIP customers",
      "contact_uuid": "11112222-3333-4444-8555-666677778888",
      "added": true
    }
  }
}

DELETE

Remove a contact from a group

https://app.driptell.com/api/v1/contact-groups/{uuid}/contacts

Remove an existing contact from a contact group without deleting the contact.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

uuidstringRequired: The group's UUID.

Body parameters

contact_uuidstringRequired: The contact's UUID.

Body raw (JSON)

JSON body

{
  "contact_uuid": "11112222-3333-4444-8555-666677778888"
}

Error responses 1

404: The contact or group does not exist in this workspace.

Example request

cURL

curl --request DELETE 'https://app.driptell.com/api/v1/contact-groups/8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d/contacts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "contact_uuid": "11112222-3333-4444-8555-666677778888"
}'

Example response

200

JSON

{
  "success": true,
  "data": {
    "membership": {
      "id": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d:11112222-3333-4444-8555-666677778888",
      "group_uuid": "8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "group_name": "VIP customers",
      "contact_uuid": "11112222-3333-4444-8555-666677778888",
      "removed": true
    }
  }
}

GET

Find recent Zapier event records

https://app.driptell.com/api/v1/webhook-events

Fetch real workspace records when testing an instant Zapier trigger.

Returns recent Zapier event payloads from this workspace. Contact triggers can also use recent contacts before a subscription exists. Other triggers return an empty array until a matching event is recorded. No callback URLs, headers, or credentials are returned.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

eventsstringRequired: Comma-separated list of 1–10 supported event names.
limitnumber: Maximum records, from 1 to 25. Defaults to 10.

Error responses 2

400: Missing or unsupported events.
401: A valid Full API workspace key is required.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/webhook-events?events=contact.created&limit=10' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "events": [
      {
        "event": "contact.created",
        "timestamp": "2026-09-09T10:00:00.000Z",
        "data": {
          "uuid": "11112222-3333-4444-8555-666677778888",
          "first_name": "Jane",
          "phone": "+971500000000"
        }
      }
    ]
  }
}

GET

List Zapier subscriptions

https://app.driptell.com/api/v1/webhook-subscriptions

List the Zapier event subscriptions created with the current API key.

Subscriptions are isolated by workspace and API key. A key can only view or remove subscriptions that it created.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/webhook-subscriptions' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "uuid": "44445555-6666-4777-8888-9999aaaabbbb",
        "target_url": "https://hooks.zapier.com/hooks/standard/123/example/",
        "label": "New incoming message",
        "is_active": true,
        "events": [
          "message.received"
        ]
      }
    ]
  }
}

POST

Create a Zapier subscription

https://app.driptell.com/api/v1/webhook-subscriptions

Subscribe a Zapier hook to one or more workspace events.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

target_urlstringRequired: Secure hooks.zapier.com callback URL.
eventsstring[]Required: One or more supported event names.
labelstring: A short label identifying the Zapier trigger.
whatsapp_connection_scopestring: default_only (default), selected, or all_connections. Cannot exceed this API key's number access.
whatsapp_connection_uuidsstring[]: Required when scope is selected. Only the listed numbers are included; add the default number explicitly if you want it included.

Body raw (JSON)

JSON body

{
  "target_url": "https://hooks.zapier.com/hooks/standard/123/example/",
  "events": [
    "message.received"
  ],
  "label": "New incoming message",
  "whatsapp_connection_scope": "default_only"
}

Things to know

Only secure hooks.zapier.com destinations are accepted.
Creating the same callback again updates its events instead of making a duplicate.
Existing subscriptions remain bound to the workspace default WhatsApp number. Additional numbers require explicit API-key and subscription grants.

Error responses 1

400: The callback URL is invalid or an event is unsupported.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/webhook-subscriptions' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "target_url": "https://hooks.zapier.com/hooks/standard/123/example/",
  "events": [
    "message.received"
  ],
  "label": "New incoming message",
  "whatsapp_connection_scope": "default_only"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "subscription": {
      "uuid": "44445555-6666-4777-8888-9999aaaabbbb",
      "target_url": "https://hooks.zapier.com/hooks/standard/123/example/",
      "label": "New incoming message",
      "events": [
        "message.received"
      ],
      "active": true,
      "whatsapp_connection_scope": "default_only",
      "whatsapp_connection_uuids": []
    }
  }
}

DELETE

Delete a Zapier subscription

https://app.driptell.com/api/v1/webhook-subscriptions/{uuid}

Stop event delivery for a subscription created with the current API key.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

uuidstringRequired: The subscription UUID.

Error responses 1

404: The subscription does not exist or was created by another API key.

Example request

cURL

curl --request DELETE 'https://app.driptell.com/api/v1/webhook-subscriptions/44445555-6666-4777-8888-9999aaaabbbb' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "deleted": true
  }
}

POST

Send a text message

https://app.driptell.com/api/v1/send

Send a free-form WhatsApp text message inside the 24-hour service window.

Identify the recipient by either `phone` (a contact is created automatically if new) or `contact_uuid`. Free-form messages are only allowed when the customer has messaged you within the last 24 hours; otherwise send an approved template instead.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

messagestringRequired: Message text, up to 4096 characters.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
phonestring: Recipient phone (E.164). Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID. Required unless phone is given.
first_namestring: Name to use if a new contact is created from `phone`.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "message": "Hi Jane, your order has shipped!"
}

Things to know

Subject to a per-workspace send rate limit (default 300/minute).
Returns 422 when the 24-hour service window is closed — use POST /api/v1/send/template instead.
connection_uuid selects the sender; phone/contact_uuid selects the recipient. Omit connection_uuid for the workspace default sender.

Error responses 3

400: message is missing, exceeds 4096 chars, or neither phone nor contact_uuid is provided.
422: Outside the 24-hour customer service window.
429: Send rate limit exceeded (see Retry-After header / retry_after_seconds).

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "message": "Hi Jane, your order has shipped!"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918273,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Send a template message

https://app.driptell.com/api/v1/send/template

Send an approved WhatsApp template — works outside the 24-hour window.

Templates can be sent at any time. Supply `variables` in order for the body placeholders, and `header_media_url` when the template's header is an image/video/document.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

templatestringRequired: Approved template name.
connection_uuidstring: Authorised WhatsApp sender UUID. Templates are resolved within that sender's WhatsApp Business Account.
phonestring: Recipient phone (E.164). Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID. Required unless phone is given.
languagestring: Template language code (e.g. en_US). Defaults to the template's language.
variablesstring[]: Body placeholder values, in order. Must cover every body variable.
header_media_urlstring: Public http(s) URL for a media header (image/video/document).
header_variablestring: Value for a text-header placeholder, when applicable.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "template": "order_update",
  "language": "en_US",
  "variables": [
    "Jane",
    "#10234"
  ]
}

Things to know

List available templates and their variables with GET /api/v1/templates.

Error responses 4

400: template is missing, or fewer variables supplied than the template requires.
404: Template not found or not approved.
422: A required media header URL is missing or fails validation.
429: Send rate limit exceeded.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/template' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "template": "order_update",
  "language": "en_US",
  "variables": [
    "Jane",
    "#10234"
  ]
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918274,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Send a marketing template

https://app.driptell.com/api/v1/send/marketing-template

Send an approved MARKETING template through Meta's marketing message path.

Use this for opted-in promotional sends. The endpoint requires explicit `consent_confirmed=true` so marketing sends are auditable and not mixed with service templates.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

templatestringRequired: Approved MARKETING template name.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
consent_confirmedbooleanRequired: Must be true; confirms the recipient has opted in.
consent_sourcestring: Where consent came from, e.g. website form, checkout, CRM import.
phonestring: Recipient phone (E.164). Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID. Required unless phone is given.
languagestring: Template language code.
variablesstring[]: Body placeholder values, in order.
header_media_urlstring: Public media URL when the template has a media header.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "template": "summer_offer",
  "language": "en_US",
  "variables": [
    "Jane"
  ],
  "consent_confirmed": true,
  "consent_source": "checkout opt-in"
}

Things to know

Only approved MARKETING templates are accepted.
Marketing sends are recorded in the WhatsApp commerce/platform audit tables.

Error responses 3

404: Marketing template not found or not approved.
422: consent_confirmed is not true, or required header media is invalid.
429: Send rate limit exceeded.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/marketing-template' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "template": "summer_offer",
  "language": "en_US",
  "variables": [
    "Jane"
  ],
  "consent_confirmed": true,
  "consent_source": "checkout opt-in"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918276,
    "status": "sent",
    "endpoint": "marketing_messages",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Send a media message

https://app.driptell.com/api/v1/send/media

Send an image, video, audio, document, or sticker from a public URL.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

typestringRequired: One of image, video, audio, document, sticker.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
urlstringRequired: Public http(s) URL of the media file.
phonestring: Recipient phone (E.164). Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID. Required unless phone is given.
captionstring: Optional caption (image/video/document).
filenamestring: Optional file name shown for documents.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "type": "image",
  "url": "https://cdn.example.com/promo.jpg",
  "caption": "New arrivals"
}

Things to know

Like free-form text, media messages require an open 24-hour service window.

Error responses 3

400: type is invalid or url is not a public http(s) link.
422: Outside the 24-hour customer service window.
429: Send rate limit exceeded.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/media' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "type": "image",
  "url": "https://cdn.example.com/promo.jpg",
  "caption": "New arrivals"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918275,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Download received media

https://app.driptell.com/api/send/media/fetch

Fetch a secure download URL or file stream for media received from a WhatsApp contact.

Use this after receiving a webhook with an inbound image, video, audio, document, or sticker. You can pass either the WhatsApp message ID from `messages[].id` or the media object ID from `messages[].document.id`, `messages[].audio.id`, `messages[].image.id`, etc. Set `response_type` to `url` when your integration needs JSON with a temporary download URL.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

idstring: Generic identifier. Accepts a full WhatsApp message ID starting with `wamid.` or a numeric WhatsApp media object ID.
wam_idstring: WhatsApp message ID from `messages[].id`.
media_idstring: WhatsApp media object ID from the inbound media object, such as `document.id`, `audio.id`, `image.id`, `video.id`, or `sticker.id`.
response_typestring: Set to `url` to receive a JSON response containing a temporary media URL. Omit to stream the file.

Body raw (JSON)

JSON body

{
  "wam_id": "wamid.EXAMPLE_MESSAGE_ID",
  "response_type": "url"
}

Things to know

`messages[].id` is the WhatsApp message ID. Media object IDs live inside the media payload, for example `messages[].document.id` for PDFs and `messages[].audio.id` for audio or voice notes.
Without `response_type=url`, the endpoint streams the file directly instead of returning JSON.
The request is scoped to the workspace API key, so the media must belong to the same workspace as the API key.

Error responses 3

400: No message ID, media ID, or chat UUID was supplied.
401: Missing or invalid API key.
404: The media was not found in this workspace, or the media file is no longer available.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/send/media/fetch' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "wam_id": "wamid.EXAMPLE_MESSAGE_ID",
  "response_type": "url"
}'

Example response

200

JSON

{
  "statusCode": 200,
  "success": true,
  "message": "Media URL generated successfully.",
  "data": {
    "media_url": "https://app.driptell.com/api/media/51f43544-cfca-46ee-9c42-505f2598b2f5?media_token=SIGNED_ACCESS_TOKEN",
    "media_id": 123,
    "wam_id": "wamid.EXAMPLE_MESSAGE_ID",
    "file_name": "example-document.pdf",
    "mime_type": "application/pdf"
  }
}

POST

Send a location

https://app.driptell.com/api/v1/send/location

Send a WhatsApp map pin inside the 24-hour service window.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

latitudenumberRequired: Latitude.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
longitudenumberRequired: Longitude.
namestring: Optional place name.
addressstring: Optional address.
phonestring: Recipient phone. Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "latitude": 25.1972,
  "longitude": 55.2744,
  "name": "Dubai Mall"
}

Things to know

Requires an open 24-hour service window.

Error responses 1

422: Outside the 24-hour customer service window.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/location' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "latitude": 25.1972,
  "longitude": 55.2744,
  "name": "Dubai Mall"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918277,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Send contact cards

https://app.driptell.com/api/v1/send/contacts

Send one or more WhatsApp contact-card payloads.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

contactsobject[]Required: Meta contact card objects. Max 10.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
phonestring: Recipient phone. Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "contacts": [
    {
      "name": {
        "formatted_name": "Support Team"
      },
      "phones": [
        {
          "phone": "+971500000001",
          "type": "WORK"
        }
      ]
    }
  ]
}

Things to know

Requires an open 24-hour service window.

Error responses 1

400: contacts is empty or has more than 10 cards.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/contacts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "contacts": [
    {
      "name": {
        "formatted_name": "Support Team"
      },
      "phones": [
        {
          "phone": "+971500000001",
          "type": "WORK"
        }
      ]
    }
  ]
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918278,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

POST

Send catalog products

https://app.driptell.com/api/v1/send/product

Send a single product or multi-product catalog message.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

catalog_idstringRequired: Meta catalog id.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number.
product_retailer_idstring: Single product retailer id.
productsobject[]: Multiple products or section rows.
phonestring: Recipient phone. Required unless contact_uuid is given.
contact_uuidstring: Existing contact UUID.

Body raw (JSON)

JSON body

{
  "phone": "+971500000000",
  "catalog_id": "123456789",
  "product_retailer_id": "sku-100"
}

Things to know

Requires an open 24-hour service window.
Orders submitted from catalog carts are stored in WhatsApp commerce history.

Error responses 1

400: catalog_id or product ids are missing.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/send/product' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "phone": "+971500000000",
  "catalog_id": "123456789",
  "product_retailer_id": "sku-100"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message_id": 918279,
    "status": "sent",
    "connection_uuid": "11112222-3333-4444-8555-666677778888"
  }
}

GET

List authorised WhatsApp numbers

https://app.driptell.com/api/v1/whatsapp/connections

Discover the WhatsApp sender connections this API key is allowed to use.

The immutable `uuid` is the sender selector used by multi-number endpoints. Existing keys initially return only the workspace default number; an owner must explicitly grant any additional numbers under Settings → API keys.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Things to know

Omitting connection_uuid on other endpoints preserves legacy behaviour by using the workspace default number.
Provider access tokens and Meta phone-number IDs are never returned.

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/whatsapp/connections' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "connections": [
      {
        "uuid": "11112222-3333-4444-8555-666677778888",
        "display_name": "Dubai Sales",
        "display_number": "+971500000000",
        "business_account_id": "1234567890",
        "is_default": true,
        "coexistence": true,
        "status": "connected"
      }
    ]
  }
}

GET

WhatsApp capability readiness

https://app.driptell.com/api/v1/whatsapp/capabilities

Read configuration readiness without changing a connection or enabling features.

Requires a full workspace API key. Mobile sessions and lead-capture-only keys are not accepted. This is a configuration report, not a live Meta eligibility check.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Things to know

All capability entries are returned; the example shows one.
No tokens, credentials, phone numbers or cross-workspace information are returned.
Configuration does not guarantee eligibility or successful delivery.

Error responses 1

401: Missing, revoked or insufficiently scoped API key; mobile credentials are not accepted.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/whatsapp/capabilities' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "schema_version": 1,
    "checked_at": "2026-09-15T00:00:00.000Z",
    "verification": "driptell_configuration_only",
    "capabilities": [
      {
        "key": "whatsapp_calling",
        "label": "WhatsApp voice calls",
        "status": "not_implemented",
        "detail": "Call settings and logs do not yet provide a calling service. Existing AI Calls is separate."
      }
    ]
  }
}

GET

List channels

https://app.driptell.com/api/v1/channels

Discover every DripTell channel and its workspace-specific availability.

Returns safe connection details, plan access, supported operations, message types, text limits, and reply-window rules. The WhatsApp summary represents the workspace default number; use GET /api/v1/whatsapp/connections to discover every sender authorised for the API key. Credentials and provider tokens are never returned.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Things to know

Snapchat is profile-only because its Public Profile API does not provide private Inbox conversations.
TikTok appears as planned and cannot be used through the stable public API.

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "channels": [
      {
        "key": "whatsapp",
        "label": "WhatsApp",
        "kind": "messaging",
        "release": "available",
        "status": "connected",
        "available": true,
        "connected": true,
        "plan": {
          "allowed": true,
          "current": "Business",
          "required": null
        },
        "capabilities": {
          "operations": [
            "conversations.list",
            "messages.list",
            "messages.send"
          ],
          "message_types": [
            "text",
            "template",
            "image",
            "video",
            "audio",
            "document",
            "location",
            "contacts",
            "product"
          ],
          "max_text_length": 4096,
          "reply_window_hours": 24
        },
        "connection": {
          "display_name": "Example Business",
          "display_address": "+971500000000",
          "last_synced_at": "2026-07-30T08:40:00.000Z"
        }
      }
    ]
  }
}

GET

Get channel

https://app.driptell.com/api/v1/channels/{channel}

Inspect one channel's connection state and supported operations.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

channelstringRequired: whatsapp, messenger, instagram, telegram, webchat, ai-calls, snapchat, or tiktok.

Error responses 2

401: Missing or invalid API key.
404: The channel key is unknown.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/telegram' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "channel": {
      "key": "telegram",
      "label": "Telegram",
      "status": "connected",
      "available": true,
      "connected": true,
      "capabilities": {
        "operations": [
          "conversations.list",
          "messages.list",
          "messages.send"
        ],
        "message_types": [
          "text"
        ],
        "max_text_length": 4096,
        "reply_window_hours": null
      }
    }
  }
}

GET

List channel conversations

https://app.driptell.com/api/v1/channels/{channel}/conversations

List only the Inbox conversations for one messaging channel.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

channelstringRequired: whatsapp, messenger, instagram, telegram, or webchat.

Query parameters

statusstring: Optional: open, pending, or closed.
connection_uuidstring: For channel=whatsapp, restrict results to this authorised sender. Omit to use the workspace default number.
searchstring: Search contact name, phone, email, or channel address.
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1-100. Default 25.

Things to know

This route never creates a channel identity or conversation.
Use the returned conversation UUID when listing or sending messages.
WhatsApp results include the sending-number identity. Omit connection_uuid to list only the workspace default number's conversations.

Error responses 3

401: Missing or invalid API key.
403: The active plan does not include the channel.
422: The channel does not provide Inbox conversations.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/whatsapp/conversations?connection_uuid=11112222-3333-4444-8555-666677778888&status=open&page=1&per_page=25' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "conversations": [
      {
        "uuid": "c0ffee00-1111-2222-3333-444455556666",
        "channel": "whatsapp",
        "status": "open",
        "unread_count": 1,
        "last_message_at": "2026-07-30T08:40:00.000Z",
        "reply_window_open": true,
        "contact": {
          "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
          "name": "Jane Doe",
          "phone": "+971500000000",
          "email": "jane@example.com",
          "channel_address": "+971500000000",
          "channel_display_name": "Jane Doe",
          "blocked": false
        },
        "connection_uuid": "11112222-3333-4444-8555-666677778888",
        "whatsapp_sender": {
          "uuid": "11112222-3333-4444-8555-666677778888",
          "display_name": "Dubai Sales",
          "display_number": "+971500000000",
          "is_default": false
        }
      }
    ],
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

GET

List channel messages

https://app.driptell.com/api/v1/channels/{channel}/conversations/{conversationUuid}/messages

Read a paginated, sanitized message history for one conversation.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

channelstringRequired: whatsapp, messenger, instagram, telegram, or webchat.
conversationUuidstringRequired: Conversation UUID returned by the channel conversation list.

Query parameters

connection_uuidstring: For channel=whatsapp, the authorised sender that owns the conversation. Omit for the workspace default number.
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1-100. Default 50.

Things to know

Raw provider responses, access tokens, and internal message error payloads are not returned.

Error responses 2

401: Missing or invalid API key.
404: The conversation does not exist in this workspace and channel.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/telegram/conversations/c0ffee00-1111-2222-3333-444455556666/messages?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "conversation": {
      "uuid": "c0ffee00-1111-2222-3333-444455556666",
      "channel": "telegram",
      "status": "open"
    },
    "messages": [
      {
        "uuid": "d0ffee00-1111-2222-3333-444455556666",
        "channel": "telegram",
        "direction": "inbound",
        "type": "text",
        "status": "delivered",
        "body": "Can you help me?",
        "content": {
          "text": {
            "body": "Can you help me?"
          }
        },
        "provider_message_id": "telegram:123:456",
        "is_read": false,
        "media": null,
        "created_at": "2026-07-30T08:40:00.000Z"
      }
    ],
    "page": 1,
    "per_page": 50,
    "total": 1
  }
}

POST

Send channel text

https://app.driptell.com/api/v1/channels/{channel}/messages

Send a text reply through an existing channel conversation.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

channelstringRequired: whatsapp, messenger, instagram, telegram, or webchat.

Body parameters

conversation_uuidstringRequired: Existing conversation UUID from the same workspace and channel.
connection_uuidstring: For channel=whatsapp, the authorised sender that owns the conversation. Omit for the workspace default number.
messagestringRequired: Text to send. Channel-specific limits apply.

Body raw (JSON)

JSON body

{
  "conversation_uuid": "c0ffee00-1111-2222-3333-444455556666",
  "message": "Thanks for contacting us."
}

Things to know

The recipient identity is always taken from the existing conversation; arbitrary social IDs are not accepted.
WhatsApp rich messages and templates continue to use the existing /api/v1/send/* endpoints.
All public send endpoints share the same workspace rate limit.

Error responses 7

400: conversation_uuid or message is missing or invalid.
403: The active plan does not include the channel.
404: The conversation does not exist in this workspace and channel.
409: The channel is not connected or enabled.
422: The contact is blocked, the reply window is closed, or the text exceeds the channel limit.
429: The workspace API send rate limit has been exceeded.
502: The provider rejected or could not deliver the request.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/channels/messenger/messages' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "conversation_uuid": "c0ffee00-1111-2222-3333-444455556666",
  "message": "Thanks for contacting us."
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "message": {
      "uuid": "d0ffee00-1111-2222-3333-444455556666",
      "channel": "messenger",
      "conversation_uuid": "c0ffee00-1111-2222-3333-444455556666",
      "provider_message_id": "m_mid.abc123",
      "status": "sent",
      "created_at": "2026-07-30T08:41:00.000Z"
    }
  }
}

GET

List chats or messages

https://app.driptell.com/api/v1/chats

List recent conversations, or the messages of a single contact.

Without `contact_uuid` you get the workspace conversation list (most recent first). With `contact_uuid` you get that contact's message history.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

contact_uuidstring: If set, returns this contact's messages instead of the conversation list.
connection_uuidstring: Authorised WhatsApp sender UUID. Omit to use the workspace default number while preserving non-WhatsApp results.
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1–100. Default 25.

Things to know

When `contact_uuid` is supplied the response contains `messages` (newest first) instead of `chats`.

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/chats?per_page=25' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "chats": [
      {
        "uuid": "c0ffee00-1111-2222-3333-444455556666",
        "status": "open",
        "last_message_at": "2026-06-16T08:45:00.000Z",
        "last_message_preview": "Thanks, see you then!",
        "unread_count": 0,
        "contact_uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
        "contact_name": "Jane Doe",
        "phone": "+971500000000",
        "connection_uuid": "11112222-3333-4444-8555-666677778888"
      }
    ],
    "page": 1,
    "per_page": 25
  }
}

GET

List AI call agents

https://app.driptell.com/api/v1/channels/ai-calls/agents

List the workspace's AI call agents without exposing provider credentials or system instructions.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

statusstring: Optional agent status filter.
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1-100. Default 25.

Error responses 2

401: Missing or invalid API key.
403: AI Calls is not available for the workspace.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/ai-calls/agents?status=active' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "agents": [
      {
        "uuid": "9b7bd67f-4414-4ea6-bab3-821331f3981f",
        "name": "Sales qualification",
        "direction": "both",
        "status": "active",
        "language": "en",
        "voice_name": "Professional",
        "document_count": 3,
        "phone_number_count": 1,
        "call_count": 42
      }
    ],
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

GET

List AI calls

https://app.driptell.com/api/v1/channels/ai-calls/calls

List AI call records with outcomes, contact association, duration, and workspace charge.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

statusstring: Optional call status filter.
directionstring: Optional: inbound, outbound, or browser_test.
pageinteger: Page number, starting at 1. Default 1.
per_pageinteger: Items per page, 1-100. Default 25.

Error responses 1

403: AI Calls is not available for the workspace.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/ai-calls/calls?status=completed&page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "calls": [
      {
        "uuid": "6f418324-eac9-4cbc-8049-291aec105832",
        "direction": "inbound",
        "status": "completed",
        "from_number": "+971500000000",
        "to_number": "+97140000000",
        "contact_uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
        "agent_uuid": "9b7bd67f-4414-4ea6-bab3-821331f3981f",
        "duration_seconds": 184,
        "outcome": "qualified",
        "sentiment": "positive",
        "customer_charge_minor": 87,
        "currency": "USD"
      }
    ],
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

GET

Get AI call

https://app.driptell.com/api/v1/channels/ai-calls/calls/{callUuid}

Read one AI call's result, transcript, and safe recording availability flag.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

callUuidstringRequired: Call UUID.

Things to know

Provider conversation IDs, telephony IDs, raw recording objects, credentials, and agent system instructions are excluded.

Error responses 2

403: AI Calls is not available for the workspace.
404: The call does not exist in this workspace.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/channels/ai-calls/calls/6f418324-eac9-4cbc-8049-291aec105832' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "call": {
      "uuid": "6f418324-eac9-4cbc-8049-291aec105832",
      "direction": "inbound",
      "status": "completed",
      "duration_seconds": 184,
      "outcome": "qualified",
      "sentiment": "positive",
      "summary": "Customer requested a product demo.",
      "transcript": [
        {
          "role": "agent",
          "text": "How can I help?"
        },
        {
          "role": "customer",
          "text": "I would like a demo."
        }
      ],
      "recording_available": true
    }
  }
}

GET

List templates

https://app.driptell.com/api/v1/templates

All approved message templates with their structure.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Query parameters

connection_uuidstring: Authorised WhatsApp sender UUID. Returns templates valid for its WhatsApp Business Account; omit for the workspace default number.

Things to know

Use the `name` and the body `{{n}}` placeholders to build the `variables` array for POST /api/v1/send/template.

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/templates' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "templates": [
      {
        "uuid": "55556666-7777-8888-9999-aaaabbbbcccc",
        "name": "order_update",
        "category": "UTILITY",
        "language": "en_US",
        "status": "APPROVED",
        "components": [
          {
            "type": "BODY",
            "text": "Hi {{1}}, your order {{2}} has shipped."
          }
        ],
        "created_at": "2026-04-12T10:00:00.000Z"
      }
    ]
  }
}

GET

List canned replies

https://app.driptell.com/api/v1/canned-replies

All keyword-triggered automatic replies in the workspace.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Error responses 1

401: Missing or invalid API key.

Example request

cURL

curl --request GET 'https://app.driptell.com/api/v1/canned-replies' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "canned_replies": [
      {
        "uuid": "dddd1111-eeee-2222-ffff-333344445555",
        "name": "Business hours",
        "triggers": [
          "hours",
          "open"
        ],
        "response": {
          "type": "text",
          "data": {
            "text": "We're open 9am–6pm, Sun–Thu."
          },
          "match": "contains"
        },
        "status": "active",
        "updated_at": "2026-06-01T12:00:00.000Z"
      }
    ]
  }
}

POST

Create a canned reply

https://app.driptell.com/api/v1/canned-replies

Create a keyword-triggered automatic text reply.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Body parameters

namestringRequired: Internal name for the reply.
keywordsstring[]Required: Trigger keywords (at least one).
textstringRequired: The reply text to send.
matchstring: "contains" (default) or "exact" keyword matching.

Body raw (JSON)

JSON body

{
  "name": "Business hours",
  "keywords": [
    "hours",
    "open"
  ],
  "text": "We are open 9am-6pm.",
  "match": "contains"
}

Error responses 1

400: name, keywords[], or text is missing.

Example request

cURL

curl --request POST 'https://app.driptell.com/api/v1/canned-replies' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "name": "Business hours",
  "keywords": [
    "hours",
    "open"
  ],
  "text": "We are open 9am-6pm.",
  "match": "contains"
}'

Example response

201

JSON

{
  "success": true,
  "data": {
    "canned_reply": {
      "uuid": "dddd1111-eeee-2222-ffff-333344445555",
      "name": "Business hours",
      "status": "active"
    }
  }
}

PUT

Update a canned reply

https://app.driptell.com/api/v1/canned-replies/{uuid}

Update the name, keywords, text, match mode, or active status.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json
Content-TypestringRequired: application/json

Path variables

uuidstringRequired: The canned reply's UUID.

Body parameters

namestring: New name.
keywordsstring[]: Replace the trigger keywords.
textstring: Replace the reply text.
matchstring: "contains" or "exact".
statusstring: "active" or "inactive".

Body raw (JSON)

JSON body

{
  "status": "inactive"
}

Error responses 1

404: No canned reply with that UUID exists.

Example request

cURL

curl --request PUT 'https://app.driptell.com/api/v1/canned-replies/dddd1111-eeee-2222-ffff-333344445555' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --data '{
  "status": "inactive"
}'

Example response

200

JSON

{
  "success": true,
  "data": {
    "updated": true
  }
}

DELETE

Delete a canned reply

https://app.driptell.com/api/v1/canned-replies/{uuid}

Soft-delete a canned reply.

Workspace API key

Headers

AuthorizationstringRequired: Bearer <DRIPTELL_API_KEY>
Acceptstring: application/json

Path variables

uuidstringRequired: The canned reply's UUID.

Error responses 1

404: No canned reply with that UUID exists.

Example request

cURL

curl --request DELETE 'https://app.driptell.com/api/v1/canned-replies/dddd1111-eeee-2222-ffff-333344445555' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $DRIPTELL_API_KEY"

Example response

200

JSON

{
  "success": true,
  "data": {
    "deleted": true
  }
}