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?