Developer Documentation
Developer Documentation provides technical guidance for configuring APIs, webhooks, and integrations used by the platform. This guide covers API settings, mail configuration, Stripe integration, webhook setup, and security best practices. Follow these guidelines to ensure secure, reliable integrations with external services.
Understanding Developer Configuration
The platform integrates with various external services to provide telephony, scheduling, payments, and automation capabilities. Proper configuration ensures reliable operation and security.
API Configuration
Configure API keys and credentials for external services. These enable core platform features like calling, scheduling, and payments.
Security Best Practices
Follow security best practices to protect API keys, credentials, and sensitive data. Use environment variables and proper access control.
API Settings
Configure API credentials for external services that power platform features.
Twilio Configuration
Twilio enables voice calls and SMS capabilities:
Required Credentials
- Account SID: Your Twilio Account SID (found in Twilio Console dashboard)
- Auth Token: Your Twilio Auth Token (found in Twilio Console dashboard)
Security Note: Keep Twilio credentials secure. Never commit them to version control or share them publicly. These credentials provide full access to your Twilio account.
VAPI (Vonage API) Configuration
VAPI provides alternative voice calling capabilities:
Required Credentials
- VAPI Token: Your VAPI authentication token (obtained from VAPI dashboard)
Cal.com Configuration
Cal.com enables appointment scheduling and calendar integration:
Required Credentials
- API Key: Your Cal.com API key (obtained from Cal.com settings)
- Event Type: Select the event type for appointments (configured in Cal.com)
Mail Configuration
Configure SMTP settings to enable email functionality for invitations, notifications, and system emails.
SMTP Settings
Configure SMTP settings in Settings → Mail Configuration:
Required SMTP Settings
- Driver: SMTP driver (typically "smtp" for standard SMTP servers)
- Host: SMTP server hostname (e.g., "smtp.gmail.com", "smtp.mailtrap.io")
- Port: SMTP server port (commonly 587 for TLS, 465 for SSL, 25 for unencrypted)
- Username: SMTP authentication username (usually your email address)
- Password: SMTP authentication password or app-specific password
- Encryption: Encryption method (tls, ssl, or null for unencrypted)
- From Address: Default "From" email address for system emails
- From Name: Default "From" name displayed in email clients
Common SMTP Providers: Popular SMTP services include Gmail, SendGrid, Mailgun, Amazon SES, and Mailtrap (for testing). Each has specific configuration requirements. Check your provider's documentation for exact settings.
Testing Email Configuration
After configuring SMTP settings, test email delivery:
- Send a test email from Settings (if available) or trigger a system email (e.g., user invitation)
- Check that the email is received successfully
- Verify that the "From" address and name are correct
- Check spam folders if emails are not received
- Review SMTP logs (if available) for delivery errors
Stripe API Configuration (Super Admin)
Stripe powers wallet refills and subscription billing. Configuration is restricted to Super Admins for security.
Stripe Settings
Configure Stripe in Settings → Stripe API Settings (Super Admin only):
Required Stripe Settings
- Stripe Mode: Select "test" for development or "live" for production. Test mode uses test API keys and doesn't process real payments.
- Secret Key: Your Stripe Secret Key (found in Stripe Dashboard → Developers → API keys). This key starts with "sk_test_" for test mode or "sk_live_" for live mode.
- Publishable Key: Your Stripe Publishable Key (found in Stripe Dashboard). This key starts with "pk_test_" for test mode or "pk_live_" for live mode.
- Webhook Secret: Webhook signing secret for verifying webhook authenticity (found in Stripe Dashboard → Developers → Webhooks).
Critical Security: Stripe Secret Keys provide full access to your Stripe account and can process payments. Never share these keys or commit them to version control. Only Super Admins should have access to Stripe settings.
Stripe Webhook Configuration
Configure webhooks in Stripe Dashboard to receive payment events:
- Go to Stripe Dashboard → Developers → Webhooks
- Click "Add endpoint" to create a new webhook
- Enter your platform's webhook URL (provided in Settings or documentation)
- Select events to listen for (typically payment_intent.succeeded, payment_intent.payment_failed, etc.)
- Copy the webhook signing secret and enter it in Settings → Stripe API Settings
- Test webhook delivery to verify configuration
Webhooks & CRM Integrations
The platform can send webhooks to external systems and integrate with CRMs for data synchronization.
Outbound Webhooks
The platform can send webhook notifications for various events:
Webhook Events
- Call Events: Notifications when calls are completed, including call details, status, duration, and recording URLs
- Appointment Events: Notifications when appointments are created, updated, or canceled
- Campaign Events: Notifications for campaign status changes, completion, or errors
- Contact Events: Notifications when contacts are created, updated, or flagged
Webhook Security: Always validate webhook payload signatures if provided. Use HTTPS for webhook URLs to ensure secure communication. Never process webhooks from untrusted sources.
CRM Integrations
Higher-tier plans may include CRM integrations:
Zapier
Connect the platform to thousands of apps via Zapier. Automate workflows between the platform and other services.
Native CRM Integrations
Direct integrations with popular CRMs (available on Agency plan). Sync contacts, calls, and appointments automatically.
Environment & Security
Follow security best practices to protect API keys, credentials, and sensitive data.
Environment Variables
Store credentials securely using environment variables:
Best Practices
- Use Environment Variables: Store API keys and credentials in environment variables, not in code or configuration files
- Avoid Hardcoding: Never hardcode credentials in source code, templates, or configuration files
- Separate Environments: Use different credentials for development, staging, and production environments
- Secure Storage: Use secure secret management systems (e.g., AWS Secrets Manager, HashiCorp Vault) for production
- Access Control: Restrict access to environment variables. Only authorized administrators should be able to view or modify credentials
Key Rotation
Regularly rotate API keys and credentials:
Rotation Schedule
- Periodic Rotation: Rotate API keys periodically (e.g., quarterly or annually) to reduce risk of compromise
- After Compromise: Immediately rotate keys if they're suspected to be compromised or exposed
- After Employee Departure: Rotate keys when employees with access leave the organization
- Test After Rotation: After rotating keys, test all integrations to ensure they continue working correctly
- Document Rotation: Document key rotation dates and procedures for audit purposes
Access Control
Restrict who can view or edit API settings:
Access Restrictions
- Super Admin Only: Sensitive settings (Stripe API, system configuration) should be restricted to Super Admins only
- Role-Based Access: Use roles and permissions to control who can view or edit API settings
- Audit Access: Log access to sensitive settings for security auditing
- Principle of Least Privilege: Grant access only to users who absolutely need it for their job functions
Environment Separation
Use separate configurations for different environments:
Development
Use test API keys and non-production accounts. Never use production credentials in development.
Staging
Use test or sandbox accounts that mirror production but don't affect real data or payments.
Production
Use live API keys and production accounts. Protect these credentials with the highest security measures.
Best Practices
Credential Management
- Never Commit Credentials: Never commit API keys, passwords, or secrets to version control. Use environment variables or secret management systems.
- Use Strong Passwords: Use strong, unique passwords for all API accounts. Enable two-factor authentication where available.
- Rotate Regularly: Rotate API keys and credentials periodically to reduce risk of compromise.
- Monitor Usage: Regularly monitor API usage and access logs to identify unusual activity or potential security issues.
Configuration Management
- Document Configuration: Document all API configurations, webhook URLs, and integration settings for reference and disaster recovery.
- Test Before Production: Test all API configurations in development or staging before deploying to production.
- Version Control Settings: Use version control for configuration files (without secrets) to track changes and enable rollbacks.
- Backup Configuration: Regularly backup configuration settings to enable quick recovery from failures.
Security Monitoring
- Monitor Access: Regularly review who has access to API settings and credentials. Remove access for users who no longer need it.
- Audit Logs: Enable and review audit logs for API access and configuration changes.
- Alert on Changes: Set up alerts for configuration changes, especially to sensitive settings like Stripe API keys.
- Regular Reviews: Conduct regular security reviews of API configurations and access controls.
Troubleshooting
API integration not working
Checklist:
- Verify credentials: Check that API keys and credentials are correctly entered in Settings. Ensure there are no extra spaces or typos.
- Test credentials: Test credentials directly with the provider's API or dashboard to verify they're valid.
- Check account status: Verify that your provider account is active and in good standing. Suspended accounts cannot make API calls.
- Review error logs: Check application logs for API errors. Error messages often indicate the specific issue.
- Verify permissions: Ensure API keys have the necessary permissions for the operations you're trying to perform.
- Check rate limits: Verify you haven't exceeded API rate limits. Some providers throttle requests.
Emails not sending
Checklist:
- Verify SMTP settings: Check that all SMTP settings (host, port, username, password) are correctly configured.
- Test credentials: Test SMTP credentials by sending a test email. Verify username and password are correct.
- Check port and encryption: Ensure port and encryption settings match your SMTP provider's requirements.
- Review firewall: Verify that firewalls are not blocking outbound SMTP connections on the configured port.
- Check provider limits: Verify you haven't exceeded your email provider's sending limits.
- Review email logs: Check application logs for email delivery errors. Error messages often indicate the specific issue.