Custom Functions

Custom functions let your AI bot connect to other systems during live conversations. Instead of saying "I'll check and get back to you," the bot can look up an order status, check inventory, or create a record in your CRM - all in real time, while the customer waits.

---

What Can Custom Functions Do?

Think of custom functions as giving your bot superpowers beyond just chatting. Here are real-world examples:

• Order tracking - A customer asks "Where's my order?" and the bot checks your e-commerce system and replies with the shipping status and tracking link

• Inventory check - "Do you have this in size 10?" The bot checks your stock system and gives a real-time answer

• CRM updates - When the bot qualifies a lead, it automatically creates or updates a record in HubSpot, Salesforce, or any other CRM

• Quote generation - The bot collects the customer's requirements and generates a personalized quote from your pricing system

• Booking - The bot creates an appointment in your external booking system

• Discount verification - "Is this coupon code valid?" The bot checks and confirms

• Account lookup - A returning customer is automatically recognized and their account details are pulled up

The customer never sees what happens behind the scenes. They simply experience a bot that can answer their questions with real, up-to-date information.

---

How Custom Functions Work (The Simple Version)

Here is what happens when a custom function is triggered during a conversation:

1. The customer asks something that needs real-time data (e.g., "Where's my order?")

2. The bot recognizes that it needs to use a custom function to answer

3. The bot collects any missing information from the customer (e.g., "What's your order number?")

4. DM Champ sends a request to your system (your website, CRM, or any other tool) with the relevant details

5. Your system responds with the data (e.g., order status, tracking number, delivery date)

6. The bot reads the response and crafts a natural reply: "Your order ORD-4582 has been shipped and should arrive by Friday!"

Credit cost: Each custom function call costs 1 AI credit (free if you are using Bring Your Own Key).

---

Setting Up a Custom Function (Step by Step)

Navigate to Settings > Custom Functions and click Add Function.

Step 1: Give It a Name and Description

Field	What to Enter	Example
Name	A short name using letters, numbers, and underscores	check_order_status
Description	Explain what this function does (the AI reads this to decide when to use it)	"Looks up the current status of a customer's order using their order number"
Purpose (AI Action)	Tell the AI exactly when and how to use this function	"Use this when a customer asks about their order status, shipping, or delivery. Ask for their order number first."

Tip: Be very specific in the description and purpose. The clearer you are about when the function should be used, the more reliably the bot will use it at the right time.

Step 2: Set Up the Connection

You need to tell DM Champ where to send the request:

Field	What to Enter	Example
URL	The web address of your system's endpoint	https://api.yourstore.com/v1/orders/status
Method	The type of request to send	See options below

Which method to choose:

Method	When to Use It
GET	Looking up information (order status, inventory, account details)
POST	Creating new records (support tickets, leads, bookings) or complex lookups
PUT	Updating an existing record completely
PATCH	Updating part of an existing record
DELETE	Removing a record

If you are not sure which to use, check with your developer or the documentation of the system you are connecting to. GET (for lookups) and POST (for creating records) are the most common.

Step 3: Add Authentication Headers

Most systems require authentication to accept requests. Add any required headers:

Header	Example Value
Authorization	Bearer your-api-key-here
Content-Type	application/json

Security tip: Use a dedicated API key with limited permissions. Do not use admin-level credentials.

Where to find API keys: Check the settings or developer section of the system you are connecting to (e.g., your CRM, e-commerce platform, or booking tool).

Step 4: Define the Input (What the Bot Sends)

Input parameters are the pieces of information the bot collects from the conversation and sends to your system.

For each parameter, you specify:

Property	What It Means
Name	The parameter name (must match what your system expects)
Type	What kind of data it is (text, number, true/false, etc.)
Description	Tell the AI what this information is and where to find it in the conversation
Required	If set to Yes, the bot will ask the customer for this information before proceeding

Available parameter types:

Type	What It Means
string	Text (names, order numbers, addresses)
number	A numeric value (quantity, price)
boolean	True or false (yes/no values)
object	A group of related data
array	A list of items
query_param	Text that is sent as a URL parameter instead of in the request body. Use this when your API expects data in the URL (e.g., ?order_id=123).

Example: For an order status lookup, you might define:

• order_number (string, required): "The customer's order number. Usually starts with ORD- followed by digits. Ask the customer for this if they haven't mentioned it."

• email (string, optional): "The customer's email address for additional verification. Only needed if the order number alone doesn't find a match."

What Your System Receives Automatically

In addition to the input parameters you define, DM Champ automatically includes system data with every request. Your endpoint receives this in a system field:

System Field	What It Contains
system.contactId	The DM Champ ID of the contact in the conversation
system.campaignId	The campaign ID the conversation belongs to
system.userId	Your DM Champ user ID
system.channel	The messaging channel (e.g., "whatsapp", "instagram")
system.contact	The full contact record (name, phone, email, tags, etc.)
system.campaign	The campaign configuration
system.test	true if this is a Playground test, false for live conversations

This is useful if your system needs to identify the contact, check which campaign triggered the function, or behave differently during testing.

Step 5: Map the Response (What the Bot Receives)

Response mapping tells the bot which fields to extract from the data that comes back from your system. For each field in the response you want the bot to use, provide a plain-language description:

Response Field	Description for the Bot
status	The current order status (e.g., "processing," "shipped," "delivered")
tracking_number	The shipping tracking number the customer can use to track their package
estimated_delivery	The expected delivery date
items	List of items in the order

This helps the bot present information naturally instead of just dumping raw data. The bot will say something like: "Your order ORD-4582 is shipped and on its way! The tracking number is 1Z999AA101234. It should arrive by Friday, March 7th."

---

Assigning Functions to Campaigns

After creating a custom function, you need to tell each campaign which functions it can use:

1. Open the campaign

2. Go to the Bot configuration tab

3. In the Custom Functions section, select the functions you want this campaign to use

4. Save the campaign

Only assigned functions are available to the bot for that campaign. This prevents the bot from accidentally using functions that are not relevant.

---

Testing Your Custom Functions

Before going live, test thoroughly:

1. Test your system's endpoint directly - Use a tool like Postman (or ask your developer to test) to make sure your system responds correctly

2. Test in the Playground - Simulate a conversation where the customer asks something that should trigger the function

3. Check the response - Make sure the bot correctly reads and presents the data

4. Test error scenarios - What happens if the customer gives an invalid order number? What if your system is temporarily down?

---

Complete Example: Order Status Lookup

Here is a fully configured example you can use as a template:

Basic Information:

• Name: check_order_status

• Description: "Retrieves the current status of a customer order including shipping info and tracking"

• AI Action: "Call this when a customer asks about their order status, where their package is, or when it will arrive. Always ask for the order number first."

Connection:

• URL: https://api.mystore.com/orders/lookup

• Method: POST

Headers:

• Authorization: Bearer sk_live_abc123

• Content-Type: application/json

Input Parameters:

• order_number (text, required): "The order number provided by the customer"

• customer_email (text, optional): "Customer's email for additional verification"

Response Mapping:

• order_status: "Current order status"

• tracking_url: "Link for the customer to track their shipment"

• estimated_delivery: "Expected delivery date"

• items_summary: "What was ordered"

What the conversation looks like:

Customer: Hey, where's my order?

Bot: Hi! I'd be happy to check on your order. Could you share your order number with me?

Customer: It's ORD-78234

Bot: Let me look that up for you...

Your order ORD-78234 has been shipped and is on its way! The estimated delivery date is March 10th. You can track your package here: https://tracking.example.com/1Z999AA1

Is there anything else I can help you with?

---

Complete Example: Book an Appointment

Basic Information:

• Name: create_booking

• Description: "Creates a new appointment in our booking system"

• AI Action: "Use this after confirming the date, time, and contact details with the customer. Do not call until the customer explicitly confirms they want to book."

Connection:

• URL: https://booking.mycompany.com/api/appointments

• Method: POST

Input Parameters:

• date (text, required): "Appointment date in YYYY-MM-DD format"

• time (text, required): "Appointment time in HH:MM format"

• name (text, required): "Customer's full name"

• phone (text, required): "Customer's phone number"

• service_type (text, required): "The type of service being booked"

---

Tips for Reliable Custom Functions

1. Make sure repeated requests are safe. If the same request is accidentally sent twice, it should not create duplicate records. Network hiccups can occasionally cause this.

2. Return clear error messages. If something goes wrong on your system's end, return a human-readable error. The bot will relay it to the customer gracefully.

3. Keep response times under 10 seconds. If your system takes longer, consider returning a quick acknowledgment first.

4. Handle expired or invalid credentials. If your API key expires, make sure the error message is clear so the bot knows to alert a human instead of retrying.

5. Write detailed descriptions. The AI uses your descriptions to figure out when to call the function and how to extract the right information from the conversation. Vague descriptions lead to mistakes.

6. Test with real conversations. The Playground is great for initial testing, but monitor your first few live conversations to make sure everything works with real customer queries.

7. Keep logs on your end. Ask your developer to log the requests coming from DM Champ so you can quickly debug any issues.

---

Plan Requirements

Custom functions are available on plans that include the custom functions feature. Check your subscription to confirm availability.