WhatsApp API Integration

Overview

Kraya's WhatsApp API integration lets you connect WhatsApp Business numbers using Meta's embedded signup, send and receive messages via the WhatsApp Cloud API, create and manage message templates, broadcast approved templates to multiple leads, and use organization-wide Quick Replies while chatting.

This integration enables professional WhatsApp messaging at scale, with support for media, interactive messages, automated broadcasts, and saved reply templates on the Chats page.

What you can do

• Connect one or more WhatsApp Business numbers using Meta's embedded signup
• Send and receive 1:1 messages from the Chats page (within the 24-hour customer service window)
• Use Quick Replies from the Chats sidebar to send saved text and attachments when the session is open (same library as the Chrome extension)
• Create, edit, delete, and reorder Quick Replies on Chats (admin users)
• Create and submit message templates for Meta approval
• Broadcast approved templates to selected leads or CSV import lists
• Configure automatic retries for failed broadcast messages (number of attempts and interval between attempts)
• Manage multiple WhatsApp Business accounts
• Track message delivery status and read receipts
• Send media messages (images, videos, documents, audio)
• Send interactive messages (buttons, CTAs)

How it works (user-facing)

1. Connect WhatsApp Business number: Use Meta's embedded signup flow to link your WhatsApp Business number
2. Access scope on Chats:
   • Admins can view and interact with all organization leads on Chats
   • Non-admin members can view and interact only with leads in pipelines assigned to them
3. 24-hour window: After a lead messages you, you have 24 hours to send free-form messages. After that, you must use approved templates
4. Templates: Create message templates with variables, media, and buttons. Submit them to Meta for approval
5. Chats: Use the Chats page to send 1:1 messages when the 24-hour window is open, and optionally send Quick Replies from the sidebar when that session is active
6. Broadcast: Send approved templates to multiple leads at once (requires templates, not free-form messages)

Pages and entry points

• Connect WhatsApp: https://kraya-ai.com/dashboard/whatsapp-business-accounts
• Chats: https://kraya-ai.com/dashboard/whatsapp-messages
• Templates: https://kraya-ai.com/dashboard/template-message
• Broadcast: Available via a "Broadcast Message" button on the main Dashboard page (no separate route)

Who can use it

• Signed-in users can access WhatsApp API areas based on their role and assigned pipeline access
• If your organization plan restricts premium features, a banner may ask you to upgrade before using WhatsApp features
• Chats access by role:
  • Admins: Can access all chats in the organization
  • Non-admin members: Can access only chats for leads in their assigned pipelines
  • If a non-admin has no assigned pipelines, Chats loads with no visible conversations
• Quick Replies on Chats: All users can open the Quick Replies tab, browse categories, and send a quick reply when the messaging session is open. Admin users can also add, edit, delete, reorder groups and replies, and edit message text inline in the list

Multi-number support

• You can connect multiple WhatsApp Business numbers
• On Chats, Templates, and Broadcast flows, choose the active number from a dropdown
• The first active account is selected by default
• Each number operates independently with its own conversations and templates

CTWA attributes required in your organization

To fetch click-to-WhatsApp ad reference data, ensure these lead attributes exist in your organization:

• wa_ref_body
• wa_ref_headline
• wa_ref_ctwa_clid
• wa_ref_image_url
• wa_ref_video_url
• wa_ref_thumbnail_url
• wa_ref_source_id
• wa_ref_media_type
• wa_ref_source_url
• wa_ref_source_type
• wa_ref_welcome_message

Lead source: CTWA tagging

Leads created through the inbound WhatsApp webhook — that is, when someone messages your WhatsApp Business number for the first time, with or without coming from a click-to-WhatsApp ad — are automatically tagged with source = CTWA when the lead row is created in Kraya. You'll see this on the lead's Personal Info → Source field and in any filter or report that surfaces lead source.

This is set on the inbound path itself, not by a separate process, so it applies to:

• New conversations from organic WhatsApp messages to your number
• Click-to-WhatsApp ad replies (where the wa_ref_* attributes above are also populated)
• Both API and hosted-WhatsApp account types

Existing leads that already have a different source value (e.g., IndiaMART, Google Sheet) are not overwritten — only newly created leads pick up CTWA.

For sync into the WAPI Broadcasts pipeline: only leads in the Qualified stage are eligible to sync. Leads in any other stage on that pipeline stay local until you move them to Qualified.

Step-by-step guide

1) Connect a WhatsApp Business number (Embedded Signup)

Steps:

1. Go to Connect WhatsApp: https://kraya-ai.com/dashboard/whatsapp-business-accounts
2. Click "Link WhatsApp Business". This opens Meta's embedded signup flow
3. Follow the on-screen steps:
   • Log in to your Facebook account
   • Select or create a Facebook Business Manager
   • Grant necessary permissions
   • Complete the WhatsApp Business setup
4. When you finish, your phone number appears in the table with a status
5. If you see "setup in progress", wait a moment and refresh; when complete, status will change to "Active"

Notes:

• You can connect more than one number. Each active number will appear in the dropdowns across Chats/Templates/Broadcast
• If a number already exists in your org, the app will not add a duplicate
• You need admin permissions in Facebook Business Manager to complete the setup
• The embedded signup flow handles all the technical integration automatically

UI references:

Troubleshooting:

• If the account shows as "setup in progress" for too long, refresh the page after 1–2 minutes
• If linking fails, retry the flow. Ensure you are using the correct Facebook Business Manager and have admin permissions there
• If you see permission errors, check your Facebook Business Manager settings and ensure you have the necessary roles

2) Chats page (1:1 messaging via WhatsApp API)

Where:

• https://kraya-ai.com/dashboard/whatsapp-messages

What you can do:

• Select your WhatsApp number from the dropdown at the top-left
• Search and pick a lead conversation from the left panel
• See the full conversation in the center panel with message types, media previews, and ticks for delivery status
• Reply with text, images, videos, documents, audio, and interactive messages where supported
• If the 24-hour customer service window is closed, the text input will be disabled. Use a template instead (see Templates section)

Messaging rules and behavior:

24-hour window:

• When a lead sends you a message, a 24-hour customer service window opens
• During this window, you can send free-form messages (text, media, interactive)
• When the window is closed, you cannot send a free-form message. The input will be disabled and you'll be prompted to use a template
• When the window is closed, send an approved template to re-initiate contact (templates can be sent any time). The free-form window itself reopens when the lead replies — not when you send the template. After the lead responds, the 24-hour window reopens and the input re-enables. (Kraya sets the session's open/close time only on the lead's incoming message; this matches Meta's WhatsApp Cloud API, where only a customer message reopens the customer-service window.)
• The window closes 24 hours after the lead's last message to you

Delivery status:

• Each outgoing message shows status as ticks and updates as the message progresses:
  • Single tick: Sent (message sent to WhatsApp servers)
  • Double tick: Delivered (message delivered to lead's device)
  • Double blue tick: Read (message read by lead)
• Failure shows the error code in the message row (when available)
• Status updates are received via webhooks from Meta

Supported message types (1:1):

• Text: Plain text messages with link previews
• Image: JPEG, PNG images with optional captions
• Video: MP4 videos with optional captions
• Document: PDF, DOC, DOCX, and other document types with optional captions
• Audio: Audio files (voice messages)
• Interactive: Buttons, CTAs, and other interactive elements (supported where applicable)

Attachments:

• When replying with media, you can attach files and send during the open session
• File size limits apply (see Template section for limits)
• Media is uploaded to Kraya's servers and then sent via WhatsApp API

Left sidebar (conversations list):

Account selector:

• Pick which WhatsApp number's conversations to view
• Changing the account refreshes the list to show conversations for that number

Search:

• Find conversations by lead name, phone number, or email
• Typing updates results in real-time
• Try pasting a full phone number for best matches
• Search is case-insensitive

Filters:

• All chats: Default view with all conversations
• Unread: Only conversations with unread messages
• Failed: Conversations whose latest message shows a failed status
• Needs reply: Conversations where the latest message is from the lead or otherwise awaiting your response

Sorting and updates:

• The list shows the most recent conversations at the top
• New inbound/outbound messages move the conversation to the top automatically
• Conversations are sorted by last message timestamp

Unread badge:

• Each conversation shows a running unread count
• Opening the conversation marks messages as read
• Unread count updates in real-time

Snippet and time:

• Each item shows the last message snippet and timestamp
• Timestamps respect your organization timezone

Infinite scroll:

• The list loads more conversations as you scroll (20 at a time)
• No pagination needed; just scroll to load more

Deep links:

• If you're redirected with pre-filled params (e.g., phone and account), the app auto-selects the matching account and opens that conversation when possible
• If that lead is outside your allowed pipeline scope, the conversation may not open for non-admin users
• Useful for linking from other parts of the app

Session indicator:

• When the 24-hour session is closed, you'll see it in the chat area (input disabled)
• Use a template to resume the conversation

UI references:

Right sidebar (when a chat is open):

Layout and tabs:

• Personal Info: Manage lead profile, stage/pipeline, attributes, activity, and notes
• Call Tracker: See upcoming reminder, add/mark done, and update call outcomes
• Auto Followups: Assign or review auto follow-up sequences for this lead
• Template Message: Search approved templates and send template messages from the sidebar
• Quick Replies: Browse saved quick replies by group, preview content, and send when the session is open (see detailed subsection below)

Personal Info:

• Lead name and email: Inline editable; changes save on blur (email validated)
• Pipeline and stage:
  • Change stage from the dropdown. If your org uses auto follow-ups, you'll be prompted to apply a sequence when moving stages
  • Changing pipeline resets stage selection. You can then choose the correct stage in that pipeline
  • Lead Won sale amount (Kraya internal org only): Only if you are signed into Kraya’s internal CRM organization (production organization ID 9d92b3d7-9f52-4ec7-8214-dc724b0a965f, staging 9e6fbee5-6a01-4f31-8880-4808033043c7) does saving Lead Won from the pipeline and stage update flow show Sale Amount first. Enter the sale amount in INR and click Confirm. The value is saved on the lead as Amount Sold. If Amount Sold was set earlier, it may appear pre-filled. Other organizations never see this. Full behavior and surfaces: Dashboard.
• Attributes:
  • Add new custom attributes (key-value), edit existing ones, or bulk delete via the delete modal
• Activity history: See recent updates related to the lead (stage changes, sequence assignments, etc.)
• Notes: Maintain free-form notes; saves on blur

Call Tracker:

• Next Reminder card: Displays status (Overdue, Today, Upcoming) with the scheduled date and optional notes tooltip
• Actions:
  • Add Reminder: Schedule follow-ups with date/time and notes
  • Mark Reminder Done: Clears the current reminder and optionally prompts you to add the next one
• Calls list: Shows standard and follow-up calls (including AI bump-up and status/update calls when applicable)
  • Click the checkbox to open the call update modal and set result (e.g., Done, No Response), duration, and notes
  • When a follow-up call is completed or marked as no response, a subsequent follow-up call entry auto-appears
• Timestamps: Respect your organization timezone

Template Message (sidebar):

• Search: Search by template name, infinite scroll to browse approved templates
• Send: Click the Send icon to open the template composer and send to the current lead
• Session awareness:
  • If the 24-hour session is open and you choose a supported interactive/media type, the app can send a session message variant
  • Otherwise, it sends a template message via the API to re-initiate contact (the session reopens once the lead replies, not on the template send)

Quick Replies (sidebar tab):

Quick replies are shared for the whole organization (the same list appears in the Chrome extension). Use them to send predefined text and file attachments in one action while the customer service session is open (same condition as typing a normal reply in the chat).

• Opening the tab: Select Quick Replies on the right sidebar. The list loads when you open this tab for the selected conversation.
• Groups: Replies are grouped into categories. Each group header shows a sent count versus total for the current lead (for example, how many replies in that group have already been sent to this lead). Category names may appear in a readable form (words with spaces and capitals).
• Admins — reordering:
  • Drag a group using the handle on the left of the group row to change the order of groups. A confirmation message appears when the new order is saved.
  • Expand a group, then drag a reply using the handle on that reply row to change the order inside the group.
• Expanding a reply: Click the row to expand. You see the message text and any attachments (file names are links you can open).
• Preview text: In the expanded view, placeholders such as the lead’s first name, your first name, organization name, email, and lead attributes are shown as they would read for this lead so you can check the wording before sending. The message that is actually delivered is finalized when you send (placeholders with no value show as empty in the sent message).
• Admins — quick edit in the list: Click the message text in the expanded view to edit in place. When you click away, your changes are saved if the text changed.
• Send:
  • Use the green send icon on the reply row, or the Send button at the bottom of the expanded preview.
  • Sending is only allowed while the session is open. If the session has ended, the send controls are disabled; hover to see a hint to send a template message first to reopen the conversation.
  • If you try to send when the session is closed, you may see a message asking you to send a template to reopen the conversation.
  • While a send is in progress, that reply’s send controls show a loading state so you cannot double-send.
• After send: A success message appears. New messages show in the chat thread as usual. If the main text sent but one or more attachments failed, you may see an additional warning with details. The lead’s “sent” tracking updates so Sent at (with date and time in your organization’s timezone) can appear on that reply for this lead.
• Admins — add or manage:
  • Click + Add a Quick Reply to open the create dialog.
  • Click the edit (pencil) icon on a reply to open the edit dialog.
  • Create a Quick Reply / Edit a Quick Reply dialog fields:
    • Template Title (required): Shown as the reply name in the list. For new replies, the title must produce a unique internal key (if a title would duplicate an existing reply, you will be asked to use a different title).
    • Group (required): Choose an existing group, or + Add a New Group, then enter a name and use Add (or Cancel to go back). Empty or duplicate group names are not allowed.
    • Message Content (required): The message body. Use the + {lead_name}, + {user_name}, + {org_name}, + {email} chips, and chips for your organization’s attribute names to insert placeholders at the cursor. A short tip explains using placeholders for personalization.
    • Add Attachments: Optional files (types such as JPEG, PNG, PDF, Word, and plain text as offered in the file picker). Files upload when selected; you can remove an attachment before saving.
  • Save saves the reply; Cancel closes without saving on create. On edit, Delete asks for confirmation, then removes the reply.
• Empty organization list: If there are no quick replies yet, you see No quick replies yet. Admins also see a hint to use the add button above.

Plan limits (Quick Replies):

• If your plan has reached the quick reply limit, saving a new or updated reply may show a message that the limit was reached and that you need to upgrade to add more.

Mobile behavior:

• On phones, the right sidebar appears as a bottom drawer when you tap the info icon
• Swipe down or close to dismiss

UI references:

Troubleshooting:

• Sale Amount appeared when saving Lead Won on Personal Info: Enter a valid amount in INR and click Confirm so Amount Sold is saved and the stage update can finish. This only applies to Kraya’s internal organization (see organization IDs in Dashboard); everyone else should not see this screen.
• "Message failed" with error code (e.g., 131049): This means the message cannot be delivered to maintain healthy engagement. See Meta's official error code guide for more details: Meta WhatsApp Cloud API Error Codes
• If your input is disabled: Your 24-hour session window is likely closed. Send a template to re-initiate; the input re-enables once the lead replies
• Quick Reply send fails (no open session): You will see messaging that no open session was found, or the session-expired hint. Send a Template Message to this lead from the sidebar to re-initiate; once the lead replies the session reopens and you can send the quick reply
• Quick Reply missing after someone else deleted it: If the reply no longer exists, the app may show an error and refresh the quick reply list
• If media won't upload: Try a smaller file or a different format. See template media limits below for guidance
• Messages not appearing: Refresh the page to reload conversations and messages
• Delivery status not updating: Status updates come via webhooks; wait a few seconds for updates
• Permission error while opening or sending in a chat: This usually means your user role does not have access to that lead's pipeline on Chats. Ask your admin to assign you to the required pipeline.

3) Templates page (Create, manage, and submit for approval)

Where:

• https://kraya-ai.com/dashboard/template-message

What you can do:

• Create templates with:
  • Category: Marketing or Utility (required by Meta)
  • Multiple components: Header (text/image/video/document), Body (with variables like {{name}}), Footer, and Buttons (Quick Reply, URL, Call Phone, Copy Code)
  • Sample values for variables: Required for submission (used for template preview)
• Submit templates for approval (status moves from Draft → Pending → Approved/Rejected)
• Duplicate and edit templates
• Filter by business number, categories, statuses, and search

Language:

• English (en_US) is supported by default
• Template language is set during creation and cannot be changed after submission

Template statuses:

• Draft: Local draft in Kraya; not yet submitted to Meta
• Pending: Submitted to WhatsApp for approval; awaiting Meta's decision (typically takes a few hours to a few days)
• Approved: Ready to use in chats (outside 24h) and broadcasts
• Rejected: When Meta returns a reason, it is shown in a tooltip on the Rejected status chip. You can't edit a submitted template — duplicate it, fix the copy, and resubmit

Header media limits (when creating templates):

• Images: up to 5 MB (JPEG, PNG)
• Videos: up to 16 MB (MP4)
• Documents: up to 10 MB (PDF)

Template components:

Header:

• Optional text, image, video, or document
• Media must meet size and format requirements
• Text headers are limited in length

Body:

• Required text content
• Can include variables like {{name}}, {{email}}, etc.
• Variables must have sample values for submission
• Variables cannot be placed at the very beginning or end of the body text. Add text before and after all variables (e.g., Hello {{name}}, welcome! is valid, but {{name}} welcome or Thanks, {{name}} is not). This applies to standard templates and to each carousel card body
• Body text has character limits (varies by category)
• Optimize with AI (standard templates): An Optimize with AI action appears next to the body character counter. Clicking it opens an Instructions modal where you can give optional guidance (for example: "Make it more compelling", "Shorter for SMS-style read", "Stronger CTA"). Click Generate to run the optimization — Kraya considers your organization's context, the template name (treated as the template's purpose), and the selected category (Marketing vs Utility) to produce an improved body. The optimized version appears as an inline preview with a Changes Made summary and Apply / Dismiss buttons. Apply replaces the current body with the optimized text; Dismiss clears the preview. Each optimization run costs 1 AI credit. The 1024-character template body limit is respected, and template variables ({{1}}, {{name}}, etc.) are preserved. Carousel-card body optimization is not available in this release.

Footer:

• Optional text footer
• Limited character count

Buttons:

• Quick Reply: Up to 3 buttons with text labels
• URL: Up to 2 buttons with URLs
• Call Phone: Up to 1 button with phone number
• Copy Code: Up to 1 button with code to copy
• Button text and values are required

UI references:

Troubleshooting:

• Submission blocked: Ensure all variables in the Body have sample values and any buttons have required fields (e.g., URL or phone number)
• "Variables cannot be placed at the very beginning or end of the message": Rewrite the body so that text appears before and after every variable. For carousel templates, check each card body individually
• "Unsupported file format" when adding a header: Use JPEG/PNG for images, MP4 for video, PDF for documents
• Rejected templates: Check the rejection reason in the tooltip on the Rejected chip (shown when Meta provides one), then duplicate the template, adjust content to follow WhatsApp's messaging policies, and submit the copy
• Template not appearing in dropdown: Ensure template is Approved and associated with the correct WhatsApp Business account
• Variables not working: Ensure variable names match exactly (case-sensitive) and sample values are provided

4) Broadcast (send an approved template to many leads)

Where:

• Button on the main Dashboard page

What you can do:

• Choose a connected WhatsApp number
• Select an approved template
• Choose audience source:
  • Current selections from the Dashboard: Individual leads and/or entire stages you selected in bulk actions
  • CSV upload: Map columns to lead fields; assign a pipeline and stage (same as lead import)
• Provide default values for template variables as needed
• Send the broadcast immediately or schedule it for a future date and time
• Run multiple broadcasts in parallel (both immediate and scheduled)
• Cancel a scheduled broadcast before it starts
• Track broadcast progress live
• Auto-retry messages that fail to deliver, up to a chosen number of attempts at a chosen interval

Important rules:

• Broadcasts use only Approved templates (Draft or Pending templates cannot be used)
• Non-template content cannot be broadcast (even within 24h)
• Multiple broadcasts can run in parallel (both immediate and scheduled)
• You can have up to 5 scheduled broadcasts at a time per organization
• Scheduled broadcasts must be set to at least 10 minutes in the future
• There are no explicit per-send caps in the app. Sending may be paced for reliability, and failures will be recorded per recipient
• Broadcasts respect WhatsApp's rate limits and policies

Scheduling a broadcast:

On the final confirmation screen (where you review the template and audience), you can schedule the broadcast instead of sending it immediately:

1. Check the "Schedule the broadcast" checkbox. A date and time picker appears below
2. Select a Date (format: DD/MM/YY) and Time for when the broadcast should be sent
   • The date and time default to approximately 11 minutes from now in your organization's timezone
   • The scheduled time must be at least 10 minutes in the future
3. Click "Send Now" to confirm the scheduled broadcast

If the selected date or time is invalid, you will see one of these messages:

• "Selected date and time must be in the future." — both date and time are in the past
• "Selected date must be today or a future date." — the date is in the past
• "Selected time must be greater than the current time by at least 10 minutes." — the time is too soon

The "Send Now" button is disabled until a valid future date and time are selected.

After scheduling, you will see a confirmation message: "Broadcast scheduled successfully for {date and time}".

If you are using a CSV upload with a scheduled broadcast, the CSV is imported and validated immediately when you confirm. The actual message sending is deferred until the scheduled time.

Auto-retrying failed messages:

On the broadcast confirmation screen (below the scheduling section), you can have the system automatically retry any messages that fail to deliver, without any manual action.

1. Check the "Retry failed messages" checkbox. A short note appears below it: Automatically retry messages that fail to deliver.
2. Two dropdowns appear:
   • Retry Attempts: how many times to retry per failed lead. Options: 1 time, 2 times, 3 times, 5 times. Default: 3 times
   • Retry After: how long to wait before each next attempt. Options: 8 hours, 12 hours, 16 hours, 24 hours. Default: 24 hours
3. An info note appears below the dropdowns: Meta recommends retrying failed messages after 24 hours for higher delivery chances.
4. Continue with Send Now or schedule the broadcast as normal. Retry settings apply to scheduled broadcasts too.

When retries are applied:

• A retry is scheduled when a message fails at send time (for example, a temporary API error) or when WhatsApp reports the message as failed or undelivered after it was dispatched
• Each retry waits the chosen interval, then re-sends to the same phone number using the same template and variables
• A lead being retried shows a Retrying status until it succeeds or exhausts its attempts

When retries are not applied:

• Skipped leads (missing phone number, missing required template variables) are never retried
• Leads that have already received the message successfully are never retried
• If a recipient has opted out of WhatsApp marketing messages, the lead is marked Opted Out and is not retried — this is shown alongside the Failed badge
• Certain permanent errors at the template or account level (template paused, template disabled, billing or payment issue, account policy violation, account locked) are treated as terminal and are not retried

Broadcast lifecycle with retries:

• A broadcast stays in the In Progress section of the Broadcasts page while any leads are still waiting on a scheduled retry, even after the first pass through every recipient has completed
• Once every lead has reached a final state — delivered, terminally failed, or skipped — the broadcast moves to History
• Cancelling a broadcast also cancels every pending retry for that broadcast

Reporting and statuses:

• For each recipient, you'll see whether the message was sent successfully or failed
• Failure entries show the API error code when available (e.g., 131049)
• Retrying: When auto-retry is enabled, leads waiting for their next attempt show a Retrying status with a Retry n/N counter (current attempt out of the maximum you configured). The status and counter are only shown while the broadcast is still in progress
• Opted Out: Leads whose recipient opted out of WhatsApp marketing messages show an Opted Out label alongside the Failed badge. These are not retried even when auto-retry is enabled
• Retry history: For leads that have been retried, hovering the lead's timestamps shows a Retried at: section listing each prior attempt — the error code (or "Failed" if no code was returned) and when it was tried
• Broadcast completes when all recipients are processed (successful, failed, or skipped) and every pending retry has finished
• Progress updates in real-time as messages are sent
• You can see total sent, failed, retrying, and pending counts
• The status filter on the broadcast leads view includes a Retrying option while the broadcast is in progress
• The In Progress table on the Broadcasts page shows a Retrying column with the live count of leads waiting on a retry for each broadcast
• Scheduled broadcasts appear in the "In Progress" section of the Broadcasts page until they are sent. After completion, they move to the "History" section

Broadcast Performance Overview:

• When you open the details for an in-progress broadcast, the Performance Overview section shows delivery metrics as a chart. If auto-retry is enabled, the chart includes a Retrying segment that reflects the live count of leads waiting on a retry. The Retrying segment is removed once the broadcast moves to History
• When you open the details for a completed broadcast, the Performance Overview section shows delivery metrics using horizontal progress bars instead of a chart
• A summary box at the top displays the total number of leads in the broadcast
• Main metrics (Delivered, Read, Replied) are shown as colored progress bars, each with the status label, a count, and a percentage of total leads
• Additional statuses (Sent, Failed, Skipped) appear as summary cards below the progress bars
• Each metric uses a distinct color for easy scanning

Template variables:

• Provide default values for template variables
• If a lead has the corresponding attribute (e.g., name, email), it will be used automatically
• Default values are used when lead attributes are missing
• Variables are case-sensitive and must match template variable names exactly

UI references:

Troubleshooting:

• "Maximum of 5 scheduled broadcasts allowed": You already have 5 broadcasts waiting to be sent. Cancel an existing scheduled broadcast first, then try again
• "Scheduled time must be at least 10 minutes from now": Choose a date and time that is at least 10 minutes in the future
• "Invalid scheduled_at format": The date or time you entered could not be read. Use the date and time pickers to select valid values
• CSV upload issues: Confirm your mapping (name/phone/email/etc.) and required fields; re-upload if needed
• Large audience: The app processes recipients in chunks; progress will update as it runs
• Template variables not working: Ensure variable names match exactly and default values are provided
• Broadcast stuck: Refresh the page to reload broadcast status
• Broadcast says "In Progress" even though every message has been attempted: This is expected when auto-retry is enabled — the broadcast stays in progress until every scheduled retry finishes. Check the Retrying column on the Broadcasts page to see how many leads are still waiting on a retry
• A lead is marked "Opted Out" and was not retried: That recipient has opted out of WhatsApp marketing messages on their device. The opt-out is enforced by WhatsApp, not by Kraya, and cannot be overridden from within the app
• Auto-retry didn't fix a failure: Some failures are permanent (template paused or disabled, account policy issue, account locked, billing issue). These are not retried — the Failed status is final and the underlying cause must be resolved before re-sending

Limits & behavior

• 24-hour window: Free-form messages can only be sent within 24 hours of the lead's last message. After that, use approved templates
• Chats visibility for non-admin users: Limited to leads in assigned pipelines
• Quick Replies (plan): Your subscription may limit how many quick replies you can store. If you reach the limit, saving shows a message to upgrade
• Template approval: Templates typically take a few hours to a few days to be approved by Meta
• Broadcast limits: Up to 5 scheduled broadcasts per organization at a time. Multiple broadcasts (both immediate and scheduled) can run in parallel
• Message rate limits: WhatsApp API has rate limits; messages may be paced for reliability
• File size limits:
  • Template headers: Images ≤ 5 MB, Videos ≤ 16 MB, Documents ≤ 10 MB
  • Chat messages: Similar limits apply
• Template variables: Maximum number of variables per template (varies by Meta's limits)
• Button limits:
  • Quick Reply: Up to 3 buttons
  • URL: Up to 2 buttons
  • Call Phone: Up to 1 button
  • Copy Code: Up to 1 button

Common edge cases and how to handle them

• 24-hour window closed on Chats:

  • The input is disabled. Send an approved template to re-initiate contact. The window reopens — and the input re-enables — once the lead replies; then you can continue 1:1 free-form chatting
  • Note: sending the template does not by itself reopen the free-form window; the lead's reply does

• opens Chats but target lead is missing:

  • For non-admin users, the lead may be outside assigned pipeline scope
  • Confirm pipeline assignment with your admin

• Message shows failed with an error code (e.g., 131049):

  • See Meta WhatsApp Cloud API Error Codes
  • Common error codes:
    • 131049: Message cannot be delivered (engagement quality issue)
    • 131026: Invalid phone number
    • 131051: Template parameter mismatch
  • Consider adjusting message content or using a different approach (e.g., a different template)

• Template rejected:

  • When Meta returns a reason, Kraya shows it in a tooltip on the Rejected status chip — read it, then duplicate the template, update copy/components to align with WhatsApp policies, and submit the copy
  • Common rejection reasons:
    • Prohibited content (spam, misleading information)
    • Incorrect category selection
    • Button URLs not working
    • Template structure issues

• Media not sending:

  • Try a smaller file, or supported formats. For template headers: Image ≤ 5 MB, Video (MP4) ≤ 16 MB, Document (PDF) ≤ 10 MB
  • Ensure file format is supported (JPEG/PNG for images, MP4 for video, PDF for documents)

• Opt-outs:

  • Automated opt-out keywords (e.g., "STOP") are not enforced by Kraya. You should handle opt-outs manually (e.g., stop messaging that lead)
  • Consider maintaining an opt-out list or using lead attributes to track opt-outs

• Multiple WhatsApp numbers:

  • Each number operates independently with its own conversations and templates
  • Ensure you select the correct number when sending messages or creating templates
  • Conversations are tied to the specific WhatsApp number

• Quick Reply with no visible text after placeholders:

  • If every placeholder is empty for this lead, the sent message may be blank text followed by any attachments. Check the preview on Chats before sending when possible

• Quick Replies edited in two places (Dashboard and Chrome extension):

  • The list is shared. Changes made in one place appear in the other after the page or extension data is refreshed

• Template variables not replacing:

  • Ensure variable names match exactly (case-sensitive)
  • Check that lead attributes or default values are provided
  • Verify template is approved and variables are correctly formatted

• Scheduled broadcast not sending at the expected time: The system checks for scheduled broadcasts every minute. There may be a delay of up to one minute past the scheduled time before the broadcast begins sending. If a scheduled broadcast still has not started after a few minutes, refresh the page and check its status

• Maximum scheduled broadcasts reached: If you see "Maximum of 5 scheduled broadcasts allowed," cancel one of your existing scheduled broadcasts from the Dashboard banner or the Broadcasts page, then try scheduling again

• CSV import fails for a scheduled broadcast: If the CSV import encounters errors, the broadcast is marked as failed regardless of the schedule. Fix the CSV file and create a new broadcast

• Cancelling a scheduled broadcast: You can cancel a scheduled broadcast at any time before it starts sending. Once a broadcast begins processing, cancelling stops remaining messages but does not recall messages already sent

Troubleshooting

Decision tree: I can open Chats but don't see expected leads

• Are you an admin?
  • Yes → Check selected WhatsApp account and search/filter state
  • No → Confirm the lead is in one of your assigned pipelines
• If still missing → Ask admin to verify your pipeline assignments and retry

Decision tree: Chat input is disabled

• Is the 24-hour session closed?
  • Yes → Send a template to re-initiate; the input re-enables once the lead replies
  • No → Refresh the page and retry
  • No → Check if you selected the correct WhatsApp number

Decision tree: I get "Forbidden" or permission error while opening/sending

• Is the lead in your assigned pipeline scope?
  • No → Request pipeline access from admin
  • Yes → Refresh and retry
• If still not working → Contact support with lead phone number and account used

Decision tree: Message fails with error code

• Check the code against Meta docs → Adjust template/content accordingly → Retry
• Common fixes:
  • 131049: Improve message quality, avoid spam-like content
  • 131026: Verify phone number format
  • 131051: Check template variable names and values

Decision tree: Broadcast won't start

• Is the maximum of 5 scheduled broadcasts reached?
  • Yes → Cancel an existing scheduled broadcast first
• Is the scheduled time at least 10 minutes in the future?
  • No → Choose a later time
• Is your template Approved?
  • No → Wait for approval or use an approved template
• Is your audience selection valid?
  • No → Verify lead selection or CSV upload
• Is a WhatsApp number selected?
  • No → Select a connected WhatsApp Business number

Decision tree: Template won't submit

• Ensure header media is valid and within limits
• Fill sample values for all variables
• Ensure URLs/phone numbers are valid (for buttons)
• Check template structure (header, body, footer, buttons)
• Verify category is selected (Marketing or Utility)

Decision tree: Template rejected

• Review WhatsApp Business Policy
• Check template content for prohibited material
• Verify button URLs are working
• Ensure category matches template purpose
• Edit and resubmit

FAQs

• Can I connect multiple WhatsApp numbers?

  • Yes. Pick which number to use from the dropdowns on Chats, Templates, and Broadcasts. Each number operates independently.

• Can every member see all chats?

  • No. Admins can see all organization chats. Non-admin members can only see chats for leads in pipelines assigned to them.

• Why is my Chats list empty even though I can open the page?

  • This usually means your user has no pipeline assignments for Chats visibility. Ask your admin to assign pipelines.

• Can I broadcast non-template text?

  • No. Broadcasts require Approved templates. This is a WhatsApp API requirement.

• Can I send non-template messages to a lead outside the 24-hour window?

  • No. Send an approved template to re-initiate. The window reopens — letting you send free-form messages again for 24 hours — once the lead replies to your message. The template send alone does not reopen the free-form window.

• Do I see delivery/read receipts?

  • Yes, outgoing messages display ticks and status updates (sent, delivered, read). Failures show error codes where available.

• Are there sending caps or rate limits?

  • The app does not impose a hard cap for broadcasts. Messages may be paced for reliability. Follow WhatsApp's policies for best deliverability. WhatsApp API has rate limits that are enforced by Meta.

• Are WhatsApp sends billed as credits?

  • Credits are linked to AI features (e.g., AI replies). WhatsApp API sends are not counted as AI credits. However, WhatsApp API usage may be subject to Meta's pricing.

• How long does template approval take?

  • Typically a few hours to a few days. Meta reviews templates for compliance with WhatsApp Business policies.

• Can I edit a template after submission?

  • Once submitted, you cannot edit a template. You can duplicate it, make changes, and submit as a new template.

• What happens if a template is rejected?

  • The template status changes to "Rejected". When Meta provides a reason, Kraya shows it in a tooltip on the Rejected status chip — read that first. You cannot edit a submitted template; duplicate it, make changes, and submit the copy as a new template.

• Can I use the same template for multiple WhatsApp numbers?

  • Templates are tied to specific WhatsApp Business accounts. You may need to create separate templates for each number.

• How do I reopen a 24-hour window?

  • Send an approved template message to re-initiate the conversation. The 24-hour free-form window reopens when the lead replies to you — the template send by itself does not reopen it.

• What are Quick Replies on the Chats page?

  • They are saved messages (with optional files) shared across your organization. On the Chats page, open Quick Replies in the right sidebar, expand a reply, and send while the session is open. Admins can manage them here or in the Chrome extension.

• Why is the Quick Reply Send button disabled?

  • The customer service session is closed. Send a template message from Template Message first, then try again.

• Do Quick Replies replace {lead_name} and custom fields the same way on the web as in the extension?

  • Yes. Built-in placeholders and lead attributes are filled when the message is sent. Missing values are sent as blank. The expanded preview on Chats helps you see how it will read for the current lead.

• What file formats are supported for media?

  • Images: JPEG, PNG
  • Videos: MP4
  • Documents: PDF
  • Audio: Various formats supported by WhatsApp

• Can I schedule a broadcast for later? Yes. On the final confirmation screen, check "Schedule the broadcast," pick a date and time at least 10 minutes in the future, and click "Send Now." The broadcast will be sent automatically at the scheduled time.

• Can I run multiple broadcasts at the same time? Yes. Multiple broadcasts — both immediate and scheduled — can run in parallel. There is no longer a limit of one active broadcast at a time.

• How many broadcasts can I schedule? You can have up to 5 scheduled broadcasts waiting to be sent at the same time per organization. There is no limit on how many immediate broadcasts can run.

• Can I cancel a scheduled broadcast? Yes. Cancel a scheduled broadcast from the Dashboard banner (click "Cancel" next to the scheduled broadcast) or from the Broadcasts page (click the cancel icon on the scheduled broadcast row). A confirmation dialog will ask you to confirm before cancelling.

• What timezone is the scheduled broadcast time in? The date and time picker uses your organization's timezone. The scheduled time is displayed in that timezone throughout the app.

Related features

• Auto Followups - Creating sequences that can use WhatsApp API templates
• AI Qualification - Qualifying leads that may receive WhatsApp messages
• Dashboard - Managing leads that can receive WhatsApp messages
• Chrome Extension - WhatsApp Web overlay; same Quick Replies library as Chats for organizations using both
• Scheduled Messages — schedule a one-time approved-template message to a lead at a future date and time; works even outside the 24-hour customer service window

Screenshots/GIF placeholders