# CloudContactAI

> Cloud Contact AI is an enterprise-grade SMS, email, MMS, and voice communication platform with API/SDK integration. Features AI agents for automated customer responses and an AI chat assistant for campaign management. TCPA, FDCPA, and Reg F compliant. Trusted by collections platforms, banks, and equipment finance companies.

## Core Platform
- SMS, MMS, Email, and Voice messaging
- Bi-directional conversations
- Campaign management with split testing
- Automated flows
- White label offering
- Multi-tenant architecture with portfolio isolation
- TCPA, FDCPA, and Reg F compliance built in
- Quiet hours enforcement by state and timezone
- Automatic opt-out processing (STOP/HELP)
- Usage-based pricing (pay per message)
- A2P 10DLC brand and campaign registration
- Link shortener with click tracking
- Phone number lookup
- Multiple SMS carrier support
- Multiple email provider support (Amazon SES, Twilio SendGrid)

## AI Agents

### Contextual Auto-Responder
AI that responds to inbound customer messages using the full conversation history of that phone number - every inbound and outbound message. Not canned replies. Generates contextual, intelligent responses 24/7.
- Reads full thread context, not just the last message
- Responds instantly around the clock
- Powered by AWS Bedrock
- Respects opt-outs and quiet hours automatically

### Charlie - AI Campaign Assistant
Built-in AI chat interface that lets users manage the platform through natural language. Launch campaigns, pull analytics, draft messages, and get compliance help by asking.
- Launch SMS and email campaigns via chat
- Pull delivery stats and campaign analytics instantly
- Draft messages and email content
- Get help with compliance questions
- Examples: "Send a payment reminder to everyone 30 days past due", "What was our open rate last week?", "Draft a promo email for our holiday event"

## Integrations
- Salesforce
- HubSpot
- ActiveCampaign
- Zapier
- Shopify

## Solutions
- Debt collection (Reg F compliant SMS outreach, settlement agency deliverability)
- Banks and equipment finance (loan delinquency reduction, TCPA/FINRA compliant, portfolio separation)
- Sports facilities (booking reminders, event marketing, no-show reduction, youth leagues)
- Political campaigns

## Developer Resources
- [API Reference](https://developer.cloudcontactai.com/docs/quickstart-with-api)
- [SDK Documentation](https://developer.cloudcontactai.com/docs/introduction)
- [Node.js SDK](https://developer.cloudcontactai.com/docs/nodejs)
- [Python SDK](https://developer.cloudcontactai.com/docs/python)
- [GitHub - ccai-node](https://github.com/CloudContactAI/ccai-node)
- [AI Agents](https://cloudcontactai.com/ai-agents/)
- [Pricing](https://cloudcontactai.com/pricing)
- [Webhooks](https://developer.cloudcontactai.com/docs/webhooks)

---

## Node.js SDK Reference

### Installation

```bash
npm install ccai-node
```

### Configuration

```javascript
import { CCAI } from 'ccai-node';
import 'dotenv/config';

const ccai = new CCAI({
  clientId: process.env.CCAI_CLIENT_ID,
  apiKey: process.env.CCAI_API_KEY
});
```

Environment variables:
```
CCAI_CLIENT_ID=your-client-id
CCAI_API_KEY=your-api-key
```

### Send Single SMS

```javascript
ccai.sms.sendSingle(
  "Jane",
  "Smith",
  "+15559876543",
  "Hi ${firstName}, thanks for your interest!",
  "Single Message Test"
)
  .then(response => console.log('Success:', response))
  .catch(error => console.error('Error:', error));
```

### Send Bulk SMS Campaign

```javascript
const accounts = [
  { firstName: "John", lastName: "Doe", phone: "+15551234567" },
  { firstName: "Jane", lastName: "Smith", phone: "+15559876543" },
  { firstName: "Bob", lastName: "Johnson", phone: "+15551112222" }
];

ccai.sms.send(
  accounts,
  "Hello ${firstName} ${lastName}, this is a campaign message!",
  "Bulk SMS Campaign"
)
  .then(response => console.log('Campaign sent:', response))
  .catch(error => console.error('Error:', error));
```

### Send MMS (Single Step)

```javascript
ccai.mms.sendWithImage(
  "path/to/your/image.jpg",
  "image/jpeg",
  [{ firstName: "John", lastName: "Doe", phone: "+15551234567" }],
  "Hello ${firstName}, check out this image!",
  "MMS Campaign Example"
)
  .then(response => console.log(`MMS sent! Campaign ID: ${response.campaignId}`))
  .catch(error => console.error('Error:', error));
```

Supported media types: image/jpeg, image/png, image/gif

### Send Email

```javascript
const response = await ccai.email.sendSingle(
  "John",
  "Doe",
  "john@example.com",
  "Welcome to Our Service",
  "<p>Hello ${firstName},</p><p>Thank you for signing up!</p>",
  "noreply@yourcompany.com",
  "support@yourcompany.com",
  "Your Company",
  "Welcome Email"
);
```

### Email Campaign

```javascript
const campaign = {
  subject: "Monthly Newsletter",
  title: "July 2025 Newsletter",
  message: "<h1>Newsletter</h1><p>Hello ${firstName},</p><p>Updates...</p>",
  senderEmail: "newsletter@yourcompany.com",
  replyEmail: "reply@yourcompany.com",
  senderName: "Your Company Newsletter",
  accounts: [
    { firstName: "John", lastName: "Doe", email: "john@example.com" },
    { firstName: "Jane", lastName: "Smith", email: "jane@example.com" }
  ],
  campaignType: "EMAIL",
  addToList: "noList",
  contactInput: "accounts",
  fromType: "single",
  senders: []
};

const response = await ccai.email.sendCampaign(campaign);
```

### Schedule Email Campaign

```javascript
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(10, 0, 0, 0);

campaign.scheduledTimestamp = tomorrow.toISOString();
campaign.scheduledTimezone = "America/New_York";

const response = await ccai.email.sendCampaign(campaign);
```

### Voice

```javascript
const response = await ccai.voice.send(
  accounts,
  "Hello, this is a reminder about your appointment tomorrow at 3 PM.",
  "Appointment Reminder"
);
```

### Short Links

```javascript
const shortLink = await ccai.shortlink.create(
  "https://www.yourcompany.com/promo?utm_source=sms",
  "Summer Promo Link"
);
console.log(`Short URL: ${shortLink.url}`);
```

### Conversations & Inbox

```javascript
// Get conversation history for a phone number
const conversations = await ccai.inbox.getConversation("+15551234567");

// List inbox threads
const inbox = await ccai.inbox.list();
```

### Webhooks

```javascript
// Register
const webhook = await ccai.webhook.register({
  url: "https://your-endpoint.com/webhook",
  events: ["MESSAGE_SENT", "MESSAGE_RECEIVED"],
  secret: "your-webhook-secret"
});

// List
const webhooks = await ccai.webhook.list();

// Update
await ccai.webhook.update(webhook.id, { url: "https://new-endpoint.com/webhook" });

// Delete
await ccai.webhook.delete(webhook.id);
```

Webhook event types: DELIVERY_RECEIPT, INBOUND_MESSAGE, OPT_OUT, MESSAGE_SENT, MESSAGE_RECEIVED

Delivery receipt payload:
```json
{
  "message": "Hello John!",
  "segments": 1,
  "smsSid": 141321,
  "messageStatus": "SENT",
  "totalPrice": 0.03,
  "to": "+15551234567"
}
```

Inbound message payload:
```json
{
  "campaign": {
    "id": 141293,
    "title": "Default Campaign",
    "message": "",
    "createdAt": "2025-08-13T21:20:50.212623Z"
  },
  "from": "+15551234567",
  "to": "+14158735045",
  "message": "Reply text here"
}
```

### Verify Webhook Signatures

```javascript
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Check x-ccai-signature header against your secret
```

### A2P 10DLC Compliance

```javascript
// Register brand
const brand = await ccai.compliance.registerBrand({
  legalName: "Your Company LLC",
  taxId: "12-3456789",
  taxIdCountry: "US",
  website: "https://www.yourcompany.com",
  vertical: "TECHNOLOGY",
  entityType: "PRIVATE_PROFIT",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "94105",
    country: "US"
  },
  contactEmail: "compliance@yourcompany.com",
  contactPhone: "+14155551234"
});

// Register campaign
const campaign = await ccai.compliance.registerCampaign({
  brandId: brand.brandId,
  useCase: "MARKETING",
  description: "Promotional messages for opted-in customers",
  messageFlow: "Customers opt-in via web form and receive promotional SMS",
  sampleMessages: [
    "Hi ${firstName}, check out our latest deals at https://example.com",
    "Your order #12345 has shipped! Track it here: https://example.com/track"
  ],
  helpMessage: "Reply HELP for assistance.",
  optOutMessage: "You have been unsubscribed. Reply START to re-subscribe."
});

// Check status
const brandStatus = await ccai.compliance.getBrandStatus(brand.brandId);
const campaignStatus = await ccai.compliance.getCampaignStatus(campaign.campaignId);
```

### Error Handling

```javascript
try {
  const response = await ccai.sms.sendSingle("John", "Doe", "+15551234567", "Test", "Test");
} catch (error) {
  console.error(`Code: ${error.code}, Message: ${error.message}, Status: ${error.status}`);
}
```

Common error codes:
- 40001: Invalid API key
- 40002: Invalid request parameters
- 40003: Rate limit exceeded
- 40004: Insufficient credits
- 40101: Authentication failed
- 42201: Invalid phone number format (use E.164: +1XXXXXXXXXX)
- 42202: Recipient opted out

### Retry Pattern

```javascript
async function sendWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries || error.code === 40101) throw error;
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}
```

### Options Object

```javascript
{
  timeout: 60,          // Request timeout in seconds
  retries: 3,           // Number of retry attempts
  onProgress: (status) => {}  // Progress callback
}
```

### Module Summary

| Module | Methods |
|--------|---------|
| ccai.sms | send, sendSingle |
| ccai.mms | sendWithImage, send, sendSingle, getSignedUploadUrl, uploadImageToSignedUrl |
| ccai.email | sendSingle, sendCampaign |
| ccai.voice | send |
| ccai.shortlink | create |
| ccai.inbox | list, getConversation |
| ccai.webhook | register, list, update, delete, verifySignature, parseEvent |
| ccai.compliance | registerBrand, registerCampaign, getBrandStatus, getCampaignStatus |