API Reference
Send WhatsApp message templates using the LiveTok API.
Base URL
https://api.livetok.ai/v1
```text
## Authentication
All API requests require authentication using your API key:
```bash
curl https://api.livetok.ai/v1/messages/templates \
-H "Authorization: Bearer YOUR_API_KEY"
```text
**Get your API key:** Settings > API > Generate API Key
---
## Send Message Template
Send a WhatsApp message template to a customer. Templates are pre-approved message formats that can be sent outside the 24-hour messaging window.
```http
POST /v1/messages/templates
```text
**Parameters:**
- `to` (required) - Customer phone number in E.164 format (e.g., +1234567890)
- `template_name` (required) - Name of the approved template
- `template_language` (required) - Language code (e.g., en_US, es_MX)
- `template_parameters` (optional) - Array of parameter values for template variables
### Basic Template
Send a template without parameters:
```bash
curl https://api.livetok.ai/v1/messages/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+1234567890",
"template_name": "appointment_reminder",
"template_language": "en_US"
}'
```text
**Response:**
```json
{
"id": "msg_abc123",
"status": "sent",
"to": "+1234567890",
"template_name": "appointment_reminder",
"created_at": "2024-03-15T10:30:00Z"
}
```text
### Template with Parameters
Send a template with dynamic parameters:
```bash
curl https://api.livetok.ai/v1/messages/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+1234567890",
"template_name": "appointment_confirmation",
"template_language": "en_US",
"template_parameters": [
{
"type": "text",
"text": "John Doe"
},
{
"type": "text",
"text": "March 16, 2024"
},
{
"type": "text",
"text": "2:00 PM"
}
]
}'
```text
**Response:**
```json
{
"id": "msg_def456",
"status": "sent",
"to": "+1234567890",
"template_name": "appointment_confirmation",
"template_parameters": [
{"type": "text", "text": "John Doe"},
{"type": "text", "text": "March 16, 2024"},
{"type": "text", "text": "2:00 PM"}
],
"created_at": "2024-03-15T10:30:00Z"
}
```text
### Template with Media
Send a template that includes images or documents:
```bash
curl https://api.livetok.ai/v1/messages/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+1234567890",
"template_name": "product_announcement",
"template_language": "en_US",
"template_parameters": [
{
"type": "image",
"image": {
"link": "https://yoursite.com/product.jpg"
}
},
{
"type": "text",
"text": "Premium Package"
},
{
"type": "text",
"text": "$99.99"
}
]
}'
```text
**Response:**
```json
{
"id": "msg_ghi789",
"status": "sent",
"to": "+1234567890",
"template_name": "product_announcement",
"created_at": "2024-03-15T10:30:00Z"
}
```text
### Template with Buttons
Send a template with interactive buttons:
```bash
curl https://api.livetok.ai/v1/messages/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+1234567890",
"template_name": "appointment_reminder_buttons",
"template_language": "en_US",
"template_parameters": [
{
"type": "text",
"text": "Dr. Smith"
},
{
"type": "text",
"text": "March 16, 2024 at 2:00 PM"
}
]
}'
```text
---
## Error Handling
### Error Response Format
```json
{
"error": {
"type": "invalid_request_error",
"code": "invalid_phone_number",
"message": "The phone number provided is invalid",
"param": "to",
"doc_url": "https://docs.livetok.ai/errors#invalid_phone_number"
}
}
```text
### HTTP Status Codes
- `200` - Success
- `400` - Bad Request (invalid parameters)
- `401` - Unauthorized (invalid API key)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found (template doesn't exist)
- `429` - Too Many Requests (rate limit exceeded)
- `500` - Internal Server Error
- `503` - Service Unavailable
### Common Errors
**Invalid API Key:**
```json
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided"
}
}
```text
**Template Not Found:**
```json
{
"error": {
"type": "invalid_request_error",
"code": "template_not_found",
"message": "The template 'appointment_reminder' does not exist or is not approved"
}
}
```text
**Invalid Phone Number:**
```json
{
"error": {
"type": "invalid_request_error",
"code": "invalid_phone_number",
"message": "Phone number must be in E.164 format (e.g., +1234567890)"
}
}
```text
**Rate Limit Exceeded:**
```json
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Too many requests. Please try again later."
}
}
```text
---
## Rate Limits
**Limits by Plan:**
- Free: 1,000 requests/hour
- Pro: 10,000 requests/hour
- Enterprise: Custom limits
**Headers:**
```text
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9850
X-RateLimit-Reset: 1640995200
```text
**Handling Rate Limits:**
```javascript
const response = await fetch('https://api.livetok.ai/v1/messages/templates', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+1234567890',
template_name: 'appointment_reminder',
template_language: 'en_US'
})
});
if (response.status === 429) {
const resetTime = response.headers.get('X-RateLimit-Reset');
// Wait until reset time and retry
}
```text
---
## SDKs
### JavaScript/TypeScript
```bash
npm install @livetok/sdk
```text
```javascript
import { LiveTok } from '@livetok/sdk';
const client = new LiveTok({ apiKey: 'YOUR_API_KEY' });
// Send template without parameters
await client.messages.sendTemplate({
to: '+1234567890',
template_name: 'appointment_reminder',
template_language: 'en_US'
});
// Send template with parameters
await client.messages.sendTemplate({
to: '+1234567890',
template_name: 'appointment_confirmation',
template_language: 'en_US',
template_parameters: [
{ type: 'text', text: 'John Doe' },
{ type: 'text', text: 'March 16, 2024' },
{ type: 'text', text: '2:00 PM' }
]
});
```text
### Python
```bash
pip install livetok
```text
```python
import livetok
client = livetok.Client(api_key='YOUR_API_KEY')
# Send template without parameters
client.messages.send_template(
to='+1234567890',
template_name='appointment_reminder',
template_language='en_US'
)
# Send template with parameters
client.messages.send_template(
to='+1234567890',
template_name='appointment_confirmation',
template_language='en_US',
template_parameters=[
{'type': 'text', 'text': 'John Doe'},
{'type': 'text', 'text': 'March 16, 2024'},
{'type': 'text', 'text': '2:00 PM'}
]
)
```text
---
## Examples
### Send Appointment Reminder
```javascript
const client = new LiveTok({ apiKey: 'YOUR_API_KEY' });
await client.messages.sendTemplate({
to: '+1234567890',
template_name: 'appointment_reminder',
template_language: 'en_US',
template_parameters: [
{ type: 'text', text: 'Dr. Smith' },
{ type: 'text', text: 'tomorrow at 2:00 PM' }
]
});
```text
### Send Promotional Message
```javascript
await client.messages.sendTemplate({
to: '+1234567890',
template_name: 'special_offer',
template_language: 'en_US',
template_parameters: [
{
type: 'image',
image: { link: 'https://yoursite.com/promo.jpg' }
},
{ type: 'text', text: '20% off' },
{ type: 'text', text: 'PROMO20' }
]
});
```text
### Bulk Send Templates
```javascript
const customers = ['+1234567890', '+1987654321', '+1555555555'];
const results = await Promise.all(
customers.map(phone =>
client.messages.sendTemplate({
to: phone,
template_name: 'newsletter',
template_language: 'en_US'
})
)
);
console.log(`Sent ${results.length} messages`);
```text
---
## Knowledge Base API
Manage your AI agent's knowledge base programmatically. Add, update, and remove knowledge entries that your AI agent uses to answer customer questions.
### List Knowledge Entries
Get all knowledge base entries:
```http
GET /v1/knowledge
```text
**Parameters:**
- `limit` (optional) - Number of results (default: 20, max: 100)
- `starting_after` (optional) - Pagination cursor
- `tags` (optional) - Filter by tags
**Example:**
```bash
curl "https://api.livetok.ai/v1/knowledge?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```text
**Response:**
```json
{
"object": "list",
"data": [
{
"id": "kb_abc123",
"question": "What are your business hours?",
"answer": "We are open Monday-Friday 9 AM to 6 PM EST.",
"tags": ["hours", "general"],
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
}
],
"has_more": false
}
```text
### Create Knowledge Entry
Add a new entry to your knowledge base:
```http
POST /v1/knowledge
```text
**Parameters:**
- `question` (required) - The question or topic
- `answer` (required) - The answer or information
- `tags` (optional) - Array of tags for organization
**Example:**
```bash
curl https://api.livetok.ai/v1/knowledge \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "What payment methods do you accept?",
"answer": "We accept all major credit cards, PayPal, and bank transfers.",
"tags": ["payment", "general"]
}'
```text
**Response:**
```json
{
"id": "kb_def456",
"question": "What payment methods do you accept?",
"answer": "We accept all major credit cards, PayPal, and bank transfers.",
"tags": ["payment", "general"],
"created_at": "2024-03-15T11:00:00Z",
"updated_at": "2024-03-15T11:00:00Z"
}
```text
### Update Knowledge Entry
Update an existing knowledge base entry:
```http
PATCH /v1/knowledge/:id
```text
**Parameters:**
- `question` (optional) - Updated question
- `answer` (optional) - Updated answer
- `tags` (optional) - Updated tags array
**Example:**
```bash
curl https://api.livetok.ai/v1/knowledge/kb_abc123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{
"answer": "We are open Monday-Friday 9 AM to 7 PM EST, and Saturday 10 AM to 4 PM EST."
}'
```text
### Delete Knowledge Entry
Remove an entry from your knowledge base:
```http
DELETE /v1/knowledge/:id
```text
**Example:**
```bash
curl https://api.livetok.ai/v1/knowledge/kb_abc123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-X DELETE
```text
**Response:**
```json
{
"id": "kb_abc123",
"deleted": true
}
```text
### Bulk Import Knowledge
Import multiple knowledge entries at once:
```http
POST /v1/knowledge/bulk
```text
**Parameters:**
- `entries` (required) - Array of knowledge entries
**Example:**
```bash
curl https://api.livetok.ai/v1/knowledge/bulk \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entries": [
{
"question": "Do you offer refunds?",
"answer": "Yes, we offer full refunds within 30 days of purchase.",
"tags": ["refunds", "policy"]
},
{
"question": "How long does shipping take?",
"answer": "Standard shipping takes 5-7 business days.",
"tags": ["shipping", "delivery"]
}
]
}'
```text
**Response:**
```json
{
"imported": 2,
"failed": 0,
"entries": [
{
"id": "kb_ghi789",
"question": "Do you offer refunds?",
"status": "created"
},
{
"id": "kb_jkl012",
"question": "How long does shipping take?",
"status": "created"
}
]
}
```text
---
## Testing
### Test Mode
Use test API keys for development:
```javascript
const client = new LiveTok({
apiKey: 'sk_test_abc123',
environment: 'test'
});
```text
Test mode features:
- Separate data from production
- No real messages sent
- No charges
- All templates available for testing
---
## Support
Need help with the API?
- Chat with our AI Agent (knows the API!)
- Email developers@livetok.ai
- Check [Webhook Documentation](/developers/webhooks)
- Visit [Support Page](/support)