How to Integrate CloudContactAI into Your Application

Updated

CloudContactAI provides SDKs for C#, Go, Node.js, Perl, PHP, Python, and Ruby, so you can add SMS and email sending to your application using the language your team already works in. Integration is designed to be quick: you initialize a client with your credentials, then call a send method for single or bulk messages. This guide covers the setup steps, a working code example, how to verify it worked, and the common snags to watch for.

What You Need Before You Start

  • A CloudContactAI account. The site offers a free start with 100 SMS and emails included and no credit card required, so you can test integration before committing.
  • Your Client ID and API Key from your account. The sample code references both as YOUR-CLIENT-ID and YOUR-API-KEY.
  • The SDK package for your language. The example below uses the .NET SDK (CCAI.NET); equivalent packages exist for Go, Node.js, Perl, PHP, Python, and Ruby.
  • A destination phone number in E.164 format (for example, +15551234567), since the API expects the country code prefix.

Step 1: Install the SDK

Add the SDK package for your platform to your project. For .NET, that means referencing the CCAI.NET package; for Go, the import path shown in the documentation is github.com/cloudcontactai/ccai-go/pkg/ccai. Use the package manager native to your language (NuGet, npm, pip, Composer, gem, and so on) and confirm the package resolves before writing any sending logic.

Step 2: Initialize the Client

Create a configuration object holding your Client ID and API Key, then construct the client from it. In C#:

using CCAI.NET;
using CCAI.NET.SMS;

var config = new CCAIConfig
{
    ClientId = "YOUR-CLIENT-ID",
    ApiKey = "YOUR-API-KEY"
};

using var ccai = new CCAIClient(config);

Keep credentials out of source control. Load them from environment variables or a secrets manager rather than pasting them into the file, even during testing.

Step 3: Send a Single SMS

Call the single-send method with the recipient's name, phone number, message body, and a campaign title. The message supports personalization tokens such as ${FirstName}:

var response = await ccai.SMS.SendSingleAsync(
    firstName: "John",
    lastName: "Doe",
    phone: "+15551234567",
    message: "Hello ${FirstName}, this is a test message!",
    title: "Test Campaign"
);

Console.WriteLine($"Message sent with ID: {response.Id}");

Expected result: the call returns a response object containing a message ID. Log that ID — it is your reference for tracing the message later.

Step 4: Send to Multiple Recipients

For bulk sends, build a list of accounts and pass it to the batch method. Each account carries its own name and phone number, while the message template is shared:

var accounts = new List<Account>
{
    new Account { FirstName = "John", LastName = "Doe", Phone = "+15551234567" },
    new Account { FirstName = "Jane", LastName = "Smith", Phone = "+15559876543" }
};

var campaignResponse = await ccai.SMS.SendAsync(
    accounts: accounts,
    message: "Hello ${FirstName} ${LastName}, this is a test message!",
    title: "Bulk Test Campaign"
);

Console.WriteLine($"Campaign sent with ID: {campaignResponse.CampaignId}");

Expected result: the response returns a campaign ID rather than a single message ID. Use the campaign ID to track the batch as a whole.

How to Verify the Integration Works

  1. Send a single message to a phone number you control.
  2. Confirm the API returned a message ID without throwing an exception.
  3. Check that the message arrives, and that the ${FirstName} token resolved to the actual name rather than appearing literally.
  4. Run a two-recipient bulk send and confirm you receive a campaign ID.
  5. If you are building a multi-tenant platform, repeat the send under a second tenant's credentials to confirm messages are attributed to the right account.

Common Integration Snags

  • Phone number format. Numbers must include the country code (+1 for US numbers). A bare 10-digit number may fail or route incorrectly.
  • Unresolved personalization tokens. If ${FirstName} shows up verbatim in the delivered message, the account record for that recipient is missing the corresponding field.
  • 10DLC registration not complete. US A2P SMS traffic requires 10DLC brand and campaign registration. If your messages are accepted by the API but not delivered, registration is the first thing to check. CloudContactAI handles 10DLC registration as part of the platform, including multi-tenant registration for platforms that send on behalf of their own clients.
  • Deliverability, not just sending. A successful API response means the message was accepted, not that it landed in an inbox. The platform also addresses email spam placement and SMS delivery issues, which is worth configuring before you scale volume.
  • Credential mix-ups across tenants. In multi-tenant setups, sending with the wrong tenant's credentials attributes messages to the wrong account. Verify the client is constructed per tenant, not shared globally.

When This Integration Approach Fits

This SDK-based path suits teams that want programmatic control over sending from inside their own product, particularly platforms that send at scale or on behalf of multiple clients. CloudContactAI supports multi-tenant 10DLC and volume pricing for that use case, and the free tier (100 SMS and emails, no credit card) is enough to validate the integration end to end before you commit to a paid plan. If you only need to send occasional campaigns by hand rather than from code, the platform's chat-based campaign creation is a simpler route than building an integration at all.