API Best Practices

​

Authentication

​

API Keys

• Keep your API keys secure and never expose them in client-side code
• Use different API keys for development and production
• Rotate your API keys periodically
• Monitor your API key usage for suspicious activity

# API Key format
xxxxxxxxxxxxxxxxxxx

​

Error Handling

Implement proper error handling for API responses:

curl -X POST https://api.trillet.ai/api/v1/calls/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "toNumber": "+1234567890"
  }'

Common error responses:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits"
  }
}

{
  "error": {
    "code": "invalid_number",
    "message": "The provided phone number is invalid"
  }
}

​

Rate Limits

• Production API keys are limited to 60 requests per minute
• Implement backoff when you hit rate limits
• Monitor your API usage in the dashboard

Rate limit response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 60 seconds.",
    "reset_at": "2024-01-22T15:30:00Z"
  }
}

​

Webhooks [Coming Soon!]

​

Configuring Webhooks

1. Add your webhook URL in the dashboard
2. Configure the events you want to receive
3. Store your webhook secret securely

​

Verifying Webhooks

Always verify webhook signatures using the X-Trillet-Signature header:

# Your webhook secret from the dashboard
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Verify the signature before processing webhooks
echo -n "$PAYLOAD" | openssl sha256 -hmac "$WEBHOOK_SECRET"

​

Webhook Events

• call.started - When a call begins
• call.completed - When a call ends
• call.failed - When a call fails
• sms.sent - When an SMS is sent
• sms.delivered - When an SMS is delivered

Example webhook payload:

{
  "event": "call.completed",
  "data": {
    "callId": "call_xyz789",
    "agentId": "agent_123abc",
    "duration": 125,
    "status": "completed"
  }
}

​

Production Checklist

1. Authentication

   • Use production API keys
   • Implement key rotation
   • Secure key storage

2. Error Handling

   • Handle all error codes
   • Implement retry logic
   • Log errors appropriately

3. Monitoring

   • Track API response times
   • Monitor error rates
   • Set up alerts

4. Webhooks

   • Use HTTPS endpoints
   • Verify signatures
   • Implement retry logic
   • Handle duplicate events

​

Need Help?