3Chat Customer Growth

Create an asynchronous batch task sending text, attachments, or both to selected 3Chat customers. Each items[] independently supplies customer_id, content, attachments, channel, confirmation_token, and idempotency_key; each item needs message, attachments, or both. A task supports at most 100 items; batches of 1 to 3 are recommended to reduce channel rate-limit risk. Item idempotency keys protect their corresponding sends and do not guarantee that recreating a batch returns the same task. After receiving job_id and the initial status, query the original task with get_3chat_batch_send_status. Do not recreate the batch because of waiting, timeout, or partial failure. Attachment URLs must be final download URLs. Before sending, show recipients, sender account or channel, final content, attachments, and scope, and obtain explicit confirmation; never fabricate the confirmation represented by confirmation_token.

send_3chat_customer_messages

Read whether the authenticated 3Chat workspace has ever completed two startup milestones: publishing a 3Chat Agent and successfully connecting an eligible messaging channel. No business inputs are required. This tool does not create configuration or send messages. Returns data.workspace_id, workspace_name, readiness_status, milestones, missing_requirements, actions, checked_at, and request_id. READY means both milestones were completed; otherwise ACTION_REQUIRED is a successful result, not an error. milestones.agent_published.status and milestones.channel_connected.status are COMPLETED or NOT_COMPLETED. These historical achievements do not regress when an Agent is later unpublished or deleted, or a channel is disabled, deleted, disconnected, or unauthorized. completed_at is the known first-completion time in Unix milliseconds. Match AGENT_PUBLISHED to actions[].code=BUILD_OR_PUBLISH_AGENT and CHANNEL_CONNECTED to CONNECT_CHANNEL. Use the complete url from that same action unchanged; do not construct, translate, shorten, or rewrite it. When ready, missing_requirements and actions are empty arrays. READY does not prove current Agent operation, channel availability or authorization, customer data, or permission to send. Business tools validate current eligibility. Follow error_code, error_message, and aiAction on failure: UNAUTHORIZED requires reconnection or authorization; FORBIDDEN means no access; WORKSPACE_NOT_FOUND means the workspace is missing or inaccessible; READINESS_CHECK_FAILED means a dependency could not be read, not incomplete setup. Retry this check only when aiAction=RETRY_SAME_REQUEST.

get_3chat_workspace_readiness

Read a customer batch-send task by job_id; no task-type parameter is required. Returns data.job_id, data.task_type, data.status, data.total, data.queued, data.sent, data.failed, data.skipped, data.remaining, data.progress, data.results[], and task timestamps. data.results[].success indicates whether that individual send item was processed successfully; for false, explain its error_code and error_message. Customer results include customer_id, channel, confirmation_token, request_id, and idempotency_key. QUEUED and RUNNING are in progress; COMPLETED, PARTIAL_FAILED, FAILED, and CANCELLED are terminal. PARTIAL_FAILED may contain some or all failed items, so inspect each success value. accepted, sent, and COMPLETED describe processing, not channel delivery or reading. Tasks are retained for 24 hours; a missing or expired task does not prove messages were not sent.

get_3chat_batch_send_status

Read communication context for supplied 3Chat customer_ids in batches; this tool retrieves by ID and does not search customers. Each item is in data.results[]; a successful session is at data.results[].context.session. session.session_memory_summary summarizes lifecycle communication, session.conversations[] contains the returned conversations, and conversations[].messages[] contains messages. Apply conversation_start_time first, select each customer's latest conversations with conversation_limit, then select the latest messages per conversation with message_limit and sort them by send time. include_conversations, include_conversation_custom_fields, include_conversation_messages, and include_agent_logs control entity fields, custom fields, messages, and AI-message agent_logs respectively. NO_SESSION, NO_CONVERSATION, and NO_MESSAGE are normal no-data results within the requested scope. Consider filters, limits, include flags, warnings, and summaries; do not infer that the customer has never communicated. One failed customer does not invalidate successful items.

search_3chat_customers_context

Search customers in the connected 3Chat workspace by customer ID, name, phone, email, channel, channel account, creation time, latest inquiry time, and custom fields exposed in the live schema. Supply at least one valid filter. last_visit_start_time and last_visit_end_time filter last_visit_time, the time the customer most recently sent a message, not when a conversation was created or opened. query_mode=resolve (default) locates one customer and requires a selection if ambiguous; query_mode=list pages through all matching customers without requiring a single-customer selection. Populated fields use AND semantics. name.filter contains 1 to 100 unique names with OR semantics; use either name.value or name.filter. conditionType is FILTER for exact or FUZZY for fuzzy matching. Core results include customers[].customer_id, customerName, display_name, phone, email, channel, account_id, custom_fields, lastVisitTime, total_count, and query_mode. customers[].lastVisitTime has the same latest-customer-message meaning as last_visit_time.

search_3chat_customers

Page through one-to-one conversation entities in the current international 3Chat workspace, without message details. Filter by conversation ID, customer, channel account, status, transfer status, reply strategy, solved status, and time range; populated filters use AND semantics. session_type only accepts p2p. All parameters may be omitted: results are still limited to one-to-one conversations, with no time restriction, sorted descending by time_field (created_time by default). Pagination is by conversation. Returns data.total, data.offset, data.limit, and data.conversations[]; advance offset by limit for the next page. Entities include conversation_id, session_id, session_type, customer_id, channel_account_id, status, transfer_status, reply_strategy, solved, summary, and timestamps. No matches return total=0 and an empty conversations array. For session memory, messages, custom fields, or agent_logs, use search_3chat_customers_context.

search_3chat_conversations

Send text, attachments, or both to one specified 3Chat customer; at least one of message or attachments must be supplied. customer_id identifies the customer's unique session. If channel is omitted, the server selects an available channel. attachments[].url must be a final HTTP/HTTPS URL directly downloadable by the server, not a short URL, redirect-only link, preview page, or Markdown link. Returns customer_id, message_id, send_status, request_id, and idempotency information. accepted or sent does not prove delivery or reading. On failure, inspect error_code/errorCode, error_message/errorMsg/message, and aiAction. Retry only for RETRY_SAME_REQUEST, with identical business parameters and the original idempotency_key. Before sending, show recipients, sender account or channel, final content, attachments, and scope, and obtain explicit confirmation; never fabricate the confirmation represented by confirmation_token.

send_3chat_customer_message

Upload Base64 file content to 3Chat OSS and return data.attachment for subsequent customer messages. Use only when no final directly downloadable HTTP/HTTPS URL is available that requires no authentication or custom headers and is neither a preview page nor redirect-only link. Reuse an existing valid URL without uploading. data.attachment contains name, type, contentType, url, and size; data.attachment.url is the final download URL. Prefer passing the complete object in attachments; at minimum provide attachments[].url. File size must be greater than zero and at most 15 MiB. Supported formats: JPEG, PNG, GIF, WebP, PDF, TXT, Markdown, CSV, DOC, DOCX, XLS, and XLSX. Uploading does not send a message; uploading the same file again may create a new OSS URL.

upload_3chat_attachment