Custom Channels

Connect any messaging platform or communication tool to DM Champ using custom channels. This lets you bring messages from platforms like website live chat widgets, email systems, CRMs, or any other service into your DM Champ inbox - and respond to them with your AI bot.

---

What Are Custom Channels?

Custom channels extend DM Champ beyond its built-in messaging platforms (WhatsApp, SMS, Instagram, Messenger). With custom channels, you can:

• Receive messages from any external platform into DM Champ's unified inbox.

• Send replies from DM Champ back to your external platform automatically.

• Use the AI bot to respond to messages from any source.

• Track all conversations alongside your other channels in a single inbox.

This is ideal for businesses that use specialized communication tools, have a custom-built platform, or want all customer messages in one place.

Note: Custom channels require some technical setup. If you or your team are not comfortable with technical integrations, you may want to ask your web developer or IT team to help with this section.

---

How It Works

Custom channels work by passing messages back and forth between your external platform and DM Champ using webhooks (automated messages sent between systems over the internet). Here is the flow:

Your Platform  ──(sends message to)──>  DM Champ
                                           |
                                       AI Bot responds
                                       Contact saved
                                       Message stored
                                           |
DM Champ  ──(sends reply to)──>  Your Platform

1. Incoming messages: Your external platform sends messages to a DM Champ web address (URL). Think of it as your platform "posting" a message to DM Champ's mailbox.

2. Processing: DM Champ creates or updates the contact, stores the message, and has the AI bot generate a response (if active).

3. Outgoing messages: When DM Champ sends a reply (whether from the AI bot or typed by you), it sends the message to a URL on your platform, where your system can deliver it to the end user.

---

Setting Up Incoming Messages (Your Platform to DM Champ)

To send messages from your external platform into DM Champ, your platform needs to send data to the following URL. Your developer will recognize this as a standard POST request.

Where to Send Messages

POST https://europe-central2-whatzai.cloudfunctions.net/incomingCustomChannelMessage?apiKey=YOUR_API_KEY

Replace YOUR_API_KEY with your DM Champ API key. You can find or generate your API key in Settings > Account > API Key.

Message Format

Send the message data in the following format (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

What each part means:

• messageSid - A unique ID for this specific message (your system creates this). Used to prevent the same message from being processed twice.

• fromId - Who sent the message (could be a user ID, email, or phone number from your system).

• toId - Your business identifier (can be any label you choose).

• body - The actual message text.

• channel - A label you choose to identify where the message came from (e.g., "website-chat", "email").

Full Field Reference

Field	Required?	What It Does
customData.messageSid or customData.id	Yes	A unique ID for this message (prevents duplicates)
customData.fromId	Yes	Identifies who sent the message (e.g., a user ID, email, or phone number from your system)
customData.toId	Yes	Identifies the receiving side (your business). Can be any text you choose.
customData.body	Yes	The actual message text. Cannot be empty.
customData.status	No	Message status. Leave this out to use the default ("received").
customData.channel	No	A label for the source (e.g., "live-chat", "email", "my-crm"). Helps you identify where messages came from in your inbox.
customData.campaignId	No	A DM Champ campaign ID. Use this to route the message to a specific AI bot configuration.
customData.firstName	No	Contact's first name. Included when creating a new contact record.
customData.lastName	No	Contact's last name. Included when creating a new contact record.
customData.email	No	Contact's email address. Included when creating a new contact record.
customData.mediaUrl	No	A link to an attached file (image, video, audio, or document). Can also be a base64-encoded file (see below).
customData.mediaContentType	No	The file type (e.g., "image/jpeg", "video/mp4", "audio/ogg", "application/pdf"). Required if you include mediaUrl.
messageType	No	Type of message. Leave out for regular text. Set to "reaction" for emoji reactions.

What You Get Back

A successful request returns:

{
  "success": true,
  "messageId": "1234567890"
}

If something goes wrong, you will get an error message explaining the issue:

{
  "error": "Message body cannot be empty"
}

Status Codes

These are the response codes your system may receive. If you are not familiar with HTTP status codes, your developer will understand these:

Code	What It Means
200	Success - message received and being processed
400	Something is wrong with your request - check for missing required fields or an empty message body
405	Wrong request method - make sure you are using POST, not GET
500	Something went wrong on DM Champ's side - try again in a few moments

---

Sending Media Attachments (Images, Videos, Files)

You can include file attachments (images, videos, audio, documents) with your messages. There are two ways to do this:

Option 1: Link to a File

If the file is already hosted online, provide the URL (web address) where DM Champ can download it:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Option 2: Embed the File Directly (Base64)

If the file is not hosted online, you can embed it directly in the message as encoded text (base64 format). This is common in technical integrations where your system generates files on the fly. DM Champ will automatically decode and store the file:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Note: Embedding files directly makes the message data much larger. For big files, it is better to host the file online and send a link (Option 1) instead.

---

Setting Up Outgoing Messages (DM Champ to Your Platform)

When DM Champ sends a reply on a custom channel (whether from the AI bot or typed by you), it automatically sends that reply to a URL on your platform so your system can deliver it to the end user.

Tell DM Champ Where to Send Replies

1. Go to Settings in DM Champ.

2. Find the Custom Channel Webhook section.

3. Enter the URL on your platform where DM Champ should send outgoing messages. (Your developer will set up this URL to receive and process the replies.)

4. Click Save.

What DM Champ Sends to Your Platform

When DM Champ sends a reply, your platform will receive the following data:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-dm-champ-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

What Each Field Means

Field	What It Contains
contactId	DM Champ's internal ID for this contact
messageId	The unique ID of this message in DM Champ
userId	Your DM Champ user ID
body	The reply text
toId	The contact's ID on your platform (this matches the fromId you sent in the incoming message)
channel	The custom channel label you assigned

Your platform receives this data and uses it to deliver the reply to the end user through your own system.

How DM Champ Tracks Delivery

After sending the reply to your platform, DM Champ updates the message status:

• Sent - Your platform received the message successfully.

• Failed - Your platform returned an error or could not be reached. DM Champ stores the error details with the message so you can troubleshoot.

---

Sending Messages from Your System to DM Champ

In addition to receiving messages, you can also send outbound messages through a custom channel directly from your own system. This is useful when you want to start a conversation or send a proactive message.

Where to Send

POST https://europe-central2-whatzai.cloudfunctions.net/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Message Format

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

Required Fields

Field	What It Does
customData.fromId	The contact's ID on your platform
customData.customChannel	The name of your custom channel (e.g., "my-live-chat")
customData.body	The message text to send

The optional fields (campaignId, firstName, lastName, email) work the same as in incoming messages - they help DM Champ create or update the contact record.

What You Get Back

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "dm-champ-contact-id",
  "message": "Message sent successfully"
}

---

Real-World Examples

Here are some common ways businesses use custom channels:

Website Live Chat

Connect a live chat widget on your website to DM Champ so your AI bot can answer visitor questions:

1. A visitor types a message in your website's chat widget.

2. Your chat widget sends the message to DM Champ.

3. DM Champ's AI bot generates a response.

4. The response is sent back to your chat widget, which displays it to the visitor.

Why this is useful: Your website visitors get instant, AI-powered answers to their questions without you needing to be online.

Email

Route email conversations through DM Champ so your AI bot can respond to emails:

1. Set up a system that forwards incoming emails to DM Champ (using the email sender's address as the fromId, the email subject and body as the body, and "email" as the channel).

2. DM Champ's AI bot reads the email and generates a reply.

3. The reply is sent back to your email system, which sends it as a normal email response.

Why this is useful: Common email questions (pricing, hours, availability) get answered instantly by your AI bot.

CRM Integration

Connect your existing CRM (customer relationship management) system to DM Champ:

1. When a lead sends a message through your CRM, forward it to DM Champ.

2. DM Champ's AI bot responds and tracks the conversation.

3. The AI response is sent back to your CRM for delivery.

4. The full conversation history is available in both DM Champ and your CRM.

Why this is useful: Your sales team gets AI-assisted responses to leads without leaving their CRM.

Support Ticket System

Use DM Champ as an AI-powered first responder for customer support:

1. Your ticketing system forwards new support tickets to DM Champ.

2. The AI bot sends an initial response (e.g., acknowledging the ticket and asking clarifying questions).

3. The response is attached to the ticket in your support system.

4. Your support team can review what the AI said and take over when needed.

Why this is useful: Customers get an immediate acknowledgment and initial help, even outside business hours.

---

Troubleshooting

Messages Not Being Received by DM Champ

• Verify your API key is correct and active (check in Settings > Account > API Key).

• Make sure you are sending a POST request (not GET). Your developer will know the difference.

• Check that the customData.body field is not empty or whitespace-only.

• Verify the customData.fromId field is included.

• Read the response message for specific error details.

DM Champ Replies Not Reaching Your Platform

• Make sure you have entered your platform's URL in Settings > Custom Channel Webhook.

• Verify that the URL is publicly accessible (not behind a login or firewall) and returns a success response.

• Only replies (outgoing messages) are sent to your URL - incoming messages do not trigger this.

• Check for error details on the message in your DM Champ inbox.

Contact Not Being Created

• Make sure the fromId value is consistent for the same user across all their messages. DM Champ uses this value to identify contacts - if it changes between messages, DM Champ will create a new contact each time.

• Include firstName, lastName, and email in the first message from a new contact to create a complete contact record.

Media Attachments Not Working

• For file links (URLs), make sure the file is publicly accessible (no login required to access it).

• Always include mediaContentType when you include mediaUrl.

• For embedded files (base64), verify the format is data:MIME_TYPE;base64,ENCODED_DATA.

• Make sure the file type you specify matches the actual file content.

---

Best Practices

• Use consistent fromId values. Each user on your platform should always have the same fromId. This ensures DM Champ groups all their messages into a single conversation instead of creating duplicate contacts.

• Choose a clear channel name. Pick something descriptive like "website-chat", "email", or "zendesk" so you can easily tell where messages came from when viewing your inbox.

• Include contact details (firstName, lastName, email) in the first message from a new contact. This creates a complete, useful contact record right away.

• Build in retry logic. Have your platform retry sending messages if DM Champ does not respond on the first attempt (network hiccups happen).

• Use unique messageSid values for every message. This prevents the same message from being processed twice if your system sends it more than once.

• Use campaignId to route messages to different AI bots when you have multiple use cases (e.g., sales inquiries vs. support questions).

• Test before going live. Send test messages in both directions and verify that contacts, conversations, and AI responses all work correctly before launching to real users.