Overviewv1

DripTell public API

Build customer workflows without losing the conversation.

Connect contacts, leads, WhatsApp messages, templates, media, conversations, and automatic replies to the systems your team already uses.

Current reference

26 public operations

Production base URL, workspace-scoped authentication, and human-readable examples for every operation.

https://app.driptell.comWorkspace scopedJSON over HTTPS

Explore the API

Choose the resource that matches the workflow you are building.

2 operations

Account and health

Confirm that the API is reachable and identify the workspace attached to a key.

5 operations

Contacts

Create, find, update, and safely remove the customer records shared across DripTell.

1 operation

Leads

Bring website forms, lead ads, and partner opportunities into the DripTell pipeline.

4 operations

Contact groups

Organize contacts into reusable audiences without duplicating customer records.

8 operations

Messaging

Send WhatsApp content through the correct service-window, template, consent, and media rules.

1 operation

Conversations

Read recent customer conversations or the message history of a single contact.

1 operation

Templates

Read approved WhatsApp template names, languages, components, and placeholders before sending.

4 operations

Canned replies

Manage keyword-triggered automatic responses for repeat customer questions.

Authentication

Keep the workspace key on your server.

DripTell uses bearer API keys. Each key belongs to one workspace and grants access only to that workspace's resources.

Never place a key in browser code, a mobile bundle, analytics events, a public repository, or a support message.

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

Store securely

Use an environment secret or a managed secret store.

Rotate quickly

Revoke an exposed key and replace it in every connector.

Quickstart

Put one real customer into the workflow.

Create the contact once, keep the returned UUID, and reuse it for later leads, conversations, and messages. Phone numbers are normalized to E.164.

  1. 01

    Generate the key

    Create a server-side API key for the correct workspace.

  2. 02

    Verify the workspace

    Call /api/v1/verify before reading or writing data.

  3. 03

    Create the contact

    Keep the returned UUID as the customer identity.

Create a contact
curl --request POST "https://app.driptell.com/api/v1/contacts" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+971500000000",
    "email": "[email protected]"
  }'
201 response
{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "[email protected]"
    }
  }
}

Core concepts

Know the rules before production traffic.

These conventions apply across the public API. They make pagination, retries, security, and WhatsApp delivery behavior predictable.

Base URL

https://app.driptell.com

Every path in the reference is appended to this production host.

Authentication

Bearer API key

Keys belong to one workspace and must remain on a trusted server.

Request format

JSON over HTTPS

Send Content-Type: application/json for calls with a request body.

Pagination

page and per_page

List endpoints start at page 1 and accept up to 100 items per page.

Safe retries

Idempotency-Key

Use a stable key for lead creation and other source-driven writes.

Messaging window

24-hour service window

Use approved templates when free-form WhatsApp messaging is closed.

API reference

Every public operation, explained.

Expand an operation to see its purpose, authentication, fields, request, response, implementation notes, and possible errors.

2 operations

Account and health

Confirm that the API is reachable and identify the workspace attached to a key.

GET

Verify an API key

/api/v1/verify

Validate a bearer key and return the workspace and user context it belongs to.

GET/api/v1/verifyBearer key

Verify an API key

Validate a bearer key and return the workspace and user context it belongs to.

Use this before moving customer data. Every authenticated endpoint is automatically scoped to the workspace returned here.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/verify" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "valid": true,
    "organization": {
      "id": 8,
      "name": "Northstar Trading",
      "identifier": "northstar-trading"
    },
    "user": {
      "id": 18,
      "email": "[email protected]",
      "name": "Account Owner",
      "role": "owner"
    }
  }
}
GET

Check API health

/api/v1/health

Check whether the public API is reachable without returning workspace data.

GET/api/v1/healthPublic

Check API health

Check whether the public API is reachable without returning workspace data.

Implementation notes

  • This endpoint does not require authentication.
  • Use it for uptime monitoring and connector smoke tests, not workspace verification.
cURL request
curl --request GET "https://app.driptell.com/api/v1/health" \
  --header "Accept: application/json"
200 response
{
  "ok": true,
  "status": "ok",
  "service": "driptell-v4",
  "timestamp": "2026-07-08T00:00:00.000Z"
}

5 operations

Contacts

Create, find, update, and safely remove the customer records shared across DripTell.

GET

List contacts

/api/v1/contacts

Return a paginated list of contacts in the workspace, with optional search.

GET/api/v1/contactsBearer key

List contacts

Return a paginated list of contacts in the workspace, with optional search.

Request fields

search
querystring

Filter by name, phone, or email. Matching is case-insensitive.

page
queryinteger

Page number starting at 1. The default is 1.

per_page
queryinteger

Items per page from 1 to 100. The default is 25.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/contacts?search=Jane&page=1&per_page=25" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "contacts": [
      {
        "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+971500000000",
        "email": "[email protected]",
        "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

/api/v1/contacts

Create a customer record. DripTell normalizes the phone number to E.164.

POST/api/v1/contactsBearer key

Create a contact

Create a customer record. DripTell normalizes the phone number to E.164.

Request fields

first_namerequired
bodystring

Contact first name.

phonerequired
bodystring

Phone number in E.164 format.

last_name
bodystring

Contact last name.

email
bodystring

Contact email address.

address
bodyobject

Structured address data used by your workflow.

metadata
bodyobject

Additional workspace-specific contact data.

Possible errors

400

first_name is missing, or phone is missing or invalid.

401

The bearer key is missing, invalid, or revoked.

409

A contact with the same phone number already exists.

cURL request
curl --request POST "https://app.driptell.com/api/v1/contacts" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+971500000000",
  "email": "[email protected]"
}'
201 response
{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "[email protected]",
      "created_at": "2026-06-16T09:30:00.000Z"
    }
  }
}
GET

Get a contact

/api/v1/contacts/{uuid}

Fetch one contact by its public UUID.

GET/api/v1/contacts/{uuid}Bearer key

Get a contact

Fetch one contact by its public UUID.

Request fields

uuidrequired
pathuuid

Contact UUID returned by contact, lead, and conversation calls.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

No contact with that UUID exists in the workspace.

cURL request
curl --request GET "https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "[email protected]",
      "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

/api/v1/contacts/{uuid}

Update only the supplied contact fields. Unsent fields stay unchanged.

PUT/api/v1/contacts/{uuid}Bearer key

Update a contact

Update only the supplied contact fields. Unsent fields stay unchanged.

Request fields

uuidrequired
pathuuid

Contact UUID.

first_name
bodystring

Updated first name.

last_name
bodystring

Updated last name.

phone
bodystring

Updated E.164 phone number.

email
bodystring

Updated email address.

address
bodyobject

Replacement address object.

metadata
bodyobject

Replacement metadata object.

Possible errors

400

The supplied phone number is invalid.

401

The bearer key is missing, invalid, or revoked.

404

No contact with that UUID exists.

409

The new phone number belongs to another contact.

cURL request
curl --request PUT "https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "email": "[email protected]"
}'
200 response
{
  "success": true,
  "data": {
    "contact": {
      "uuid": "1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+971500000000",
      "email": "[email protected]",
      "updated_at": "2026-06-16T10:00:00.000Z"
    }
  }
}
DELETE

Delete a contact

/api/v1/contacts/{uuid}

Soft-delete a contact and hide it from later public API calls.

DELETE/api/v1/contacts/{uuid}Bearer key

Delete a contact

Soft-delete a contact and hide it from later public API calls.

Request fields

uuidrequired
pathuuid

Contact UUID.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

No contact with that UUID exists.

cURL request
curl --request DELETE "https://app.driptell.com/api/v1/contacts/1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "deleted": true
  }
}

1 operation

Leads

Bring website forms, lead ads, and partner opportunities into the DripTell pipeline.

POST

Create or update a lead

/api/v1/leads

Create a lead from an external payload and optionally create or reuse its contact and conversation.

POST/api/v1/leadsBearer key

Create or update a lead

Create a lead from an external payload and optionally create or reuse its contact and conversation.

DripTell updates an existing open lead for the same contact unless update_existing is false. A stable Idempotency-Key or external_source_id prevents duplicates.

Request fields

Idempotency-Key
headerstring

Stable key for a source event. Reusing it returns the original lead.

phone
bodystring

Customer phone number. Supply phone, email, or contact_uuid.

email
bodystring

Customer email. Supply phone, email, or contact_uuid.

contact_uuid
bodyuuid

Existing contact UUID.

first_name
bodystring

Customer first name when creating a contact.

last_name
bodystring

Customer last name when creating a contact.

title
bodystring

Lead title visible in the pipeline.

source
bodystring

Lead source such as website, partner, or lead_ad.

external_source_id
bodystring

Unique identifier from the originating system.

stage_name
bodystring

Target pipeline stage.

value_amount
bodynumber

Expected lead value.

value_currency
bodystring

ISO currency code for value_amount.

priority
bodystring

Workflow priority such as low, normal, or high.

lead_score
bodynumber

Optional score supplied by the source system.

custom_fields
bodyobject

Custom lead data used by the workspace.

create_conversation
bodyboolean

Create a conversation when the lead does not already have one.

Implementation notes

  • Configured outbound webhooks receive lead.created or lead.updated.
  • Use both source and external_source_id when the originating system provides a durable record ID.

Possible errors

400

No customer identity was supplied, a value is invalid, or the contact is blocked.

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request POST "https://app.driptell.com/api/v1/leads" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Idempotency-Key: source-event-8471" \
  --header "Content-Type: application/json" \
  --data '{
  "phone": "+971555535102",
  "first_name": "Wasim",
  "title": "Website enquiry",
  "source": "website",
  "external_source_id": "landing-page-12345",
  "stage_name": "New lead",
  "value_amount": 2500,
  "value_currency": "USD",
  "priority": "high",
  "custom_fields": {
    "budget": "2500 USD",
    "interest": "WhatsApp automation"
  },
  "create_conversation": true
}'
201 response
{
  "success": true,
  "data": {
    "created": true,
    "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": "Wasim",
      "phone": "+971555535102",
      "conversation_public_id": "d8e5fc33-37e3-4923-90b0-2d46d7fbf412"
    }
  }
}

4 operations

Contact groups

Organize contacts into reusable audiences without duplicating customer records.

GET

List contact groups

/api/v1/contact-groups

Return all contact groups in the workspace with their member counts.

GET/api/v1/contact-groupsBearer key

List contact groups

Return all contact groups in the workspace with their member counts.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/contact-groups" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "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

/api/v1/contact-groups

Create a named group that can be reused as a customer audience.

POST/api/v1/contact-groupsBearer key

Create a contact group

Create a named group that can be reused as a customer audience.

Request fields

namerequired
bodystring

Group name.

description
bodystring

Optional explanation of the audience.

Possible errors

400

name is missing.

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request POST "https://app.driptell.com/api/v1/contact-groups" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "VIP customers",
  "description": "High-value accounts"
}'
201 response
{
  "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

/api/v1/contact-groups/{uuid}

Rename a group or change its description.

PUT/api/v1/contact-groups/{uuid}Bearer key

Update a contact group

Rename a group or change its description.

Request fields

uuidrequired
pathuuid

Contact group UUID.

namerequired
bodystring

Updated group name.

description
bodystring

Updated group description.

Possible errors

400

name is missing.

401

The bearer key is missing, invalid, or revoked.

404

No group with that UUID exists.

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

Delete a contact group

/api/v1/contact-groups/{uuid}

Soft-delete a group without deleting the contacts inside it.

DELETE/api/v1/contact-groups/{uuid}Bearer key

Delete a contact group

Soft-delete a group without deleting the contacts inside it.

Request fields

uuidrequired
pathuuid

Contact group UUID.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

No group with that UUID exists.

cURL request
curl --request DELETE "https://app.driptell.com/api/v1/contact-groups/8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "deleted": true
  }
}

8 operations

Messaging

Send WhatsApp content through the correct service-window, template, consent, and media rules.

POST

Send a text message

/api/v1/send

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

POST/api/v1/sendBearer key

Send a text message

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

Request fields

messagerequired
bodystring

Message text, up to 4096 characters.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

first_name
bodystring

Name used if a new contact must be created from phone.

Possible errors

400

message is missing, exceeds 4096 characters, or no recipient was supplied.

401

The bearer key is missing, invalid, or revoked.

422

The 24-hour customer service window is closed. Send an approved template instead.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Send a template message

/api/v1/send/template

Send an approved WhatsApp template inside or outside the 24-hour service window.

POST/api/v1/send/templateBearer key

Send a template message

Send an approved WhatsApp template inside or outside the 24-hour service window.

Request fields

templaterequired
bodystring

Approved template name.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

language
bodystring

Template language code such as en_US.

variables
bodystring[]

Body placeholder values in the same order as {{1}}, {{2}}, and later variables.

header_media_url
bodyurl

Public image, video, or document URL required by a media header.

header_variable
bodystring

Text value required by a text header.

Possible errors

400

template is missing, or fewer variables were supplied than required.

401

The bearer key is missing, invalid, or revoked.

404

The template was not found or is not approved.

422

A required media header URL is missing or invalid.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Send a marketing template

/api/v1/send/marketing-template

Send an approved marketing template after recording explicit customer consent.

POST/api/v1/send/marketing-templateBearer key

Send a marketing template

Send an approved marketing template after recording explicit customer consent.

Marketing traffic is separated from service messages and is recorded in WhatsApp commerce and platform audit history.

Request fields

templaterequired
bodystring

Approved MARKETING template name.

consent_confirmedrequired
bodyboolean

Must be true to confirm the customer opted in.

consent_source
bodystring

Where consent was collected, such as checkout opt-in.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

language
bodystring

Template language code.

variables
bodystring[]

Ordered template body variables.

header_media_url
bodyurl

Public media URL required by the template header.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

The marketing template was not found or is not approved.

422

Consent was not confirmed, or required header media is invalid.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Send a media message

/api/v1/send/media

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

POST/api/v1/send/mediaBearer key

Send a media message

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

Request fields

typerequired
bodystring

One of image, video, audio, document, or sticker.

urlrequired
bodyurl

Public HTTPS URL for the media file.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

caption
bodystring

Optional media caption where supported.

filename
bodystring

Filename shown for a document.

Possible errors

400

type is invalid or url is not a public HTTP or HTTPS link.

401

The bearer key is missing, invalid, or revoked.

422

The 24-hour customer service window is closed. Send an approved template instead.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Download received media

/api/send/media/fetch

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

POST/api/send/media/fetchBearer key

Download received media

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

This endpoint intentionally sits outside the main /api/v1 path. The requested media must belong to the same workspace as the bearer key.

Request fields

id
bodystring

Generic message or media identity.

wam_id
bodystring

WhatsApp message ID from messages[].id.

media_id
bodystring

Media object ID from messages[].image.id, document.id, audio.id, or similar.

response_type
bodystring

Set to url for a JSON response. Omit it to stream the file.

Implementation notes

  • Use response_type=url when your integration needs JSON.
  • Without response_type=url, the successful response is the media file stream.

Possible errors

400

No message ID, media ID, or chat UUID was supplied.

401

The bearer key is missing, invalid, or revoked.

404

The media is not in this workspace or is no longer available.

cURL request
curl --request POST "https://app.driptell.com/api/send/media/fetch" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "wam_id": "wamid.HBgMOTcxNTg1OTQxMjAzFQIAEhgWM0VCMDg5M0QwQzM3MDRCMjZDQUQ2QwA=",
  "response_type": "url"
}'
200 response
{
  "statusCode": 200,
  "success": true,
  "message": "Media URL generated successfully.",
  "data": {
    "media_url": "https://app.driptell.com/api/media/3511",
    "media_id": 3511,
    "file_name": "Customer document.pdf",
    "mime_type": "application/pdf"
  }
}
POST

Send a location

/api/v1/send/location

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

POST/api/v1/send/locationBearer key

Send a location

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

Request fields

latituderequired
bodynumber

Location latitude.

longituderequired
bodynumber

Location longitude.

name
bodystring

Location name.

address
bodystring

Display address.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

Possible errors

401

The bearer key is missing, invalid, or revoked.

422

The 24-hour customer service window is closed. Send an approved template instead.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Send contact cards

/api/v1/send/contacts

Send one or more WhatsApp contact-card payloads.

POST/api/v1/send/contactsBearer key

Send contact cards

Send one or more WhatsApp contact-card payloads.

Request fields

contactsrequired
bodyobject[]

One to ten WhatsApp contact-card objects.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

Possible errors

400

contacts is empty or contains more than ten cards.

401

The bearer key is missing, invalid, or revoked.

422

The 24-hour customer service window is closed. Send an approved template instead.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

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

Send catalog products

/api/v1/send/product

Send a single product or multi-product WhatsApp catalog message.

POST/api/v1/send/productBearer key

Send catalog products

Send a single product or multi-product WhatsApp catalog message.

Request fields

catalog_idrequired
bodystring

Meta commerce catalog ID.

product_retailer_id
bodystring

Retailer ID for a single product.

products
bodyobject[]

Product sections for a multi-product message.

phone
bodystring

Recipient phone number in E.164 format. Use this or contact_uuid.

contact_uuid
bodyuuid

Existing DripTell contact UUID. Use this or phone.

Implementation notes

  • Orders submitted from catalog carts are stored in WhatsApp commerce history.

Possible errors

400

catalog_id or product identifiers are missing.

401

The bearer key is missing, invalid, or revoked.

422

The 24-hour customer service window is closed. Send an approved template instead.

429

The workspace send limit was reached. Wait for the Retry-After period before retrying.

cURL request
curl --request POST "https://app.driptell.com/api/v1/send/product" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "phone": "+971500000000",
  "catalog_id": "123456789",
  "product_retailer_id": "sku-100"
}'
201 response
{
  "success": true,
  "data": {
    "message_id": 918279,
    "status": "sent"
  }
}

1 operation

Conversations

Read recent customer conversations or the message history of a single contact.

GET

List chats or messages

/api/v1/chats

Return recent workspace conversations, or the messages for one contact.

GET/api/v1/chatsBearer key

List chats or messages

Return recent workspace conversations, or the messages for one contact.

Without contact_uuid the response contains chats. With contact_uuid it contains that contact's messages, newest first.

Request fields

contact_uuid
queryuuid

When present, return this contact's message history instead of the conversation list.

page
queryinteger

Page number starting at 1.

per_page
queryinteger

Items per page from 1 to 100.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/chats?contact_uuid=1f0a9c2e-1b3d-4e5f-9a8b-7c6d5e4f3a2b&page=1&per_page=25" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "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"
      }
    ],
    "page": 1,
    "per_page": 25
  }
}

1 operation

Templates

Read approved WhatsApp template names, languages, components, and placeholders before sending.

GET

List templates

/api/v1/templates

Return approved message templates and their current structure.

GET/api/v1/templatesBearer key

List templates

Return approved message templates and their current structure.

Implementation notes

  • Use name with POST /api/v1/send/template.
  • Build the variables array in the same order as the {{n}} placeholders in the body.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/templates" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "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"
      }
    ]
  }
}

4 operations

Canned replies

Manage keyword-triggered automatic responses for repeat customer questions.

GET

List canned replies

/api/v1/canned-replies

Return every keyword-triggered reply configured in the workspace.

GET/api/v1/canned-repliesBearer key

List canned replies

Return every keyword-triggered reply configured in the workspace.

Possible errors

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request GET "https://app.driptell.com/api/v1/canned-replies" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "canned_replies": [
      {
        "uuid": "dddd1111-eeee-2222-ffff-333344445555",
        "name": "Business hours",
        "triggers": [
          "hours",
          "open"
        ],
        "response": {
          "type": "text",
          "data": {
            "text": "We are open 9am to 6pm, Sunday to Thursday."
          },
          "match": "contains"
        },
        "status": "active",
        "updated_at": "2026-06-01T12:00:00.000Z"
      }
    ]
  }
}
POST

Create a canned reply

/api/v1/canned-replies

Create a keyword-triggered automatic text reply.

POST/api/v1/canned-repliesBearer key

Create a canned reply

Create a keyword-triggered automatic text reply.

Request fields

namerequired
bodystring

Internal reply name.

keywordsrequired
bodystring[]

Words or phrases that trigger the reply.

textrequired
bodystring

Reply sent to the customer.

match
bodystring

Keyword matching mode. For example, contains.

Possible errors

400

name, keywords[], or text is missing.

401

The bearer key is missing, invalid, or revoked.

cURL request
curl --request POST "https://app.driptell.com/api/v1/canned-replies" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Business hours",
  "keywords": [
    "hours",
    "open"
  ],
  "text": "We are open 9am to 6pm.",
  "match": "contains"
}'
201 response
{
  "success": true,
  "data": {
    "canned_reply": {
      "uuid": "dddd1111-eeee-2222-ffff-333344445555",
      "name": "Business hours",
      "status": "active"
    }
  }
}
PUT

Update a canned reply

/api/v1/canned-replies/{uuid}

Change the name, keywords, message text, match mode, or active state.

PUT/api/v1/canned-replies/{uuid}Bearer key

Update a canned reply

Change the name, keywords, message text, match mode, or active state.

Request fields

uuidrequired
pathuuid

Canned reply UUID.

name
bodystring

Updated internal name.

keywords
bodystring[]

Updated trigger terms.

text
bodystring

Updated customer reply.

match
bodystring

Updated match mode.

status
bodystring

active or inactive.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

No canned reply with that UUID exists.

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

Delete a canned reply

/api/v1/canned-replies/{uuid}

Soft-delete a canned reply.

DELETE/api/v1/canned-replies/{uuid}Bearer key

Delete a canned reply

Soft-delete a canned reply.

Request fields

uuidrequired
pathuuid

Canned reply UUID.

Possible errors

401

The bearer key is missing, invalid, or revoked.

404

No canned reply with that UUID exists.

cURL request
curl --request DELETE "https://app.driptell.com/api/v1/canned-replies/dddd1111-eeee-2222-ffff-333344445555" \
  --header "Authorization: Bearer $DRIPTELL_API_KEY" \
  --header "Accept: application/json"
200 response
{
  "success": true,
  "data": {
    "deleted": true
  }
}

Let events move the workflow.

Webhooks let connected systems react to DripTell activity without repeatedly polling the API.

Read the webhook guide

Verify the sender

Accept HTTPS traffic only and validate the configured signature or shared secret before processing a payload.

Acknowledge quickly

Return a successful response, queue the real work, and keep slow systems outside the delivery request.

Make retries safe

Store the event identity and make repeated deliveries idempotent before changing customer or order state.

Keep delivery evidence

Record the event, response, timestamp, and downstream result so a workflow can be audited and replayed.

Errors and retries

Recover from the reason, not the status alone.

Read both the HTTP status and the response body. Retry only temporary failures, use idempotency for writes, and respect Retry-After whenever it is returned.

400

Invalid request

A required field is missing or a supplied value cannot be accepted.

Correct the request before retrying.

401

Authentication failed

The bearer key is missing, invalid, or revoked.

Replace the key and verify the workspace again.

404

Resource not found

The resource does not exist inside the key's workspace.

Check the UUID and the workspace that issued the key.

409

Resource conflict

The write conflicts with an existing customer record or identity.

Read the existing resource and reconcile the identity.

422

Channel rule blocked the send

The request is valid but cannot be delivered under current channel rules.

Use an approved template or correct the required media or consent.

429

Rate limit reached

The workspace reached its current send rate.

Respect Retry-After and retry with exponential backoff.

Ready to build

Start with one customer workflow and make it dependable.

Create a workspace key, verify it, and test one complete workflow before moving production traffic.