iZap

Get conversation duration statistics (avg, min, max) for a specific date. Args: ctx: MCP request context (injected automatically). date: ISO-8601 date string, e.g. ``"2026-04-15"``. Defaults to today in ``timezone`` when omitted. end_date: ISO-8601 date string; inclusive end of the range. Omit for a single day. For a period, pass ``end_date`` in ONE call instead of one call per day (at most 92 days). timezone: IANA timezone name (default ``"UTC"``). business_id: Optional UUID of the business. Returns: A dict with ``avg_duration_seconds``, ``min_duration_seconds``, ``max_duration_seconds``, ``sessions_counted``.

get_conversation_duration

Count how many of the business's existing contacts match the audience conditions right now. Use it to size an audience before ``create_audience_transmission_preview``. All conditions are ANDed; an empty list matches every contact you can see. Only contacts in chats your account can see are counted. Args: ctx: MCP request context (injected automatically). conditions: Up to 20 filters, each an object discriminated by ``field``: ``chat_status`` (``is_any_of``/``is_none_of`` + ``values`` of ``open``, ``pending``, ``resolved``, ``archived``, ``blocked``); ``assigned_agent``/``assigned_group`` (``is_any_of``/``is_none_of`` + UUID ``values``, or ``is_unassigned``); ``assistant`` (``is_any_of``/``is_none_of`` + UUID ``values``); ``snoozed``/``ai_paused``/ ``interacted_24h`` (boolean ``value``); ``last_contact_interaction``/ ``last_agent_interaction``/``last_bot_interaction`` (``less_than``/``more_than`` + ``amount`` + ``unit`` of ``minutes``/``hours``/``days``); ``custom_field`` (``key`` + ``equals``/``not_equals``/``contains``/``is_empty``/``is_not_empty`` + ``value``). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``count``.

count_transmission_audience

Create a new AI assistant (chatbot) for the user's business. Do not use this to replace or fix an existing assistant — most plans allow only one. Call ``list_connected_assistants``, then ``update_ai_assistant_instructions`` (behavior, language) or ``update_assistant_settings`` (name, locale). Args: ctx: MCP request context (injected automatically). name: Assistant display name (1 to 100 characters). objective: Brief description of the assistant's role (optional). ai_model_name: Optional iZap brand tier to power the assistant — one of ``"iZ Lite"``, ``"iZ Pro"``, ``"iZ Max"`` or ``"iZ Core"``, each optionally suffixed with the provider code the other tools return (e.g. ``"iZ Pro · A"``). Omit to use iZap's default model. The returned ``ai_model_name`` is the same brand, never the underlying provider model. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``chatbot_id``, ``name``, ``business_id``, ``ai_model_name``.

create_ai_assistant

Use this to create a WhatsApp message template and submit it to Meta for approval. ``list_whatsapp_templates`` only lists templates Meta has already approved. Templates are what let a business start a conversation outside WhatsApp's 24-hour customer-service window, so this is the tool to reach for when ``send_whatsapp_template_message`` or a transmission needs a template that does not exist yet. Approval is Meta's, is asynchronous, and usually takes a few minutes. This tool returns as soon as the template is accepted for review with ``status`` "pending"; poll ``get_whatsapp_template_status`` with the returned ``template_id`` for the verdict. A newly created template will NOT appear in ``list_whatsapp_templates`` until Meta has it — that tool reads Meta's catalog, not local drafts. Retrying is how you fix a template: calling this again with the same ``name`` and ``language`` rewrites a template that is still a draft or was rejected, and resubmits it. A template Meta already holds (pending, approved, paused, disabled) is never rewritten — pick a different name for those. Args: ctx: MCP request context (injected automatically). name: Template name in lowercase_snake_case (e.g. ``"order_update"``). This is Meta's natural key and must be unique per language within the WABA. body_text: The message body (1 to 1024 characters). Use positional placeholders ``{{1}}``, ``{{2}}``, ... for the parts that vary per recipient; they must start at ``{{1}}`` with no gaps. language: Template language/locale code as registered with Meta (default ``"pt_BR"``). category: Meta's approval category — ``"utility"`` for transactional follow-ups, ``"marketing"`` for promotions, ``"authentication"`` for one-time codes. Picking the wrong one is the most common rejection reason. header_text: Optional single-line text header (up to 60 characters). footer_text: Optional small-print footer (up to 60 characters). buttons: Up to 10 buttons, each ``{"type": "QUICK_REPLY"|"URL"|"PHONE_NUMBER"|"VOICE_CALL"|"FLOW", "text": ...}`` plus ``url`` or ``phone_number`` for those types, or ``flow_id``, ``flow_action`` (``navigate``|``data_exchange``) and ``navigate_screen`` for FLOW. A FLOW button must be the only one; VOICE_CALL cannot be combined with PHONE_NUMBER. example_variables: One realistic sample value per body placeholder, in order (e.g. ``["Maria"]`` for a body with ``{{1}}``). Meta needs these to review a template that has placeholders. Omit them and language-appropriate samples are filled in automatically. submit_for_approval: Submit to Meta straight away (default true). Pass false to keep it a local draft for a human to review — a draft cannot be used for sending. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. waba_id: Target WhatsApp Business Account. Defaults to the business primary WABA. Returns: A dict with ``template_id``, ``name``, ``language``, ``category``, ``status`` ("draft" or "pending"), ``submitted``, ``submit_error``, ``body_variable_count`` and ``business_id``. When ``submitted`` is false and ``submit_error`` is set, the template was created but Meta refused the submission — call this tool again with the same name and the fix applied, rather than inventing a second name.

create_whatsapp_template

Book an appointment for a customer on the business's calendar. It needs ``confirmed=true``, and you may set that only after the customer has agreed to this exact day and time. Check ``check_availability`` first and offer only the times it returned. Without ``confirmed=true`` nothing is booked and the call raises "Error 400". The appointment is written to the Google Calendar the business connected, and only there: iZap keeps no copy of its own, which ``saved_in`` states. It never writes to a calendar the business did not connect, such as the user's own personal one. If the calendar does not answer, nothing is booked ("Error 503"); a time that is no longer free is "Error 409". Booking the same customer at the same time again returns the existing appointment instead of making a second one. Args: ctx: MCP request context (injected automatically). start: When it starts, ISO 8601. Without an offset it is read in the calendar's timezone (``2026-11-03T14:00:00``). It must be at least 30 minutes from now. customer_name: Who the appointment is for (1 to 100 characters). confirmed: Must be true. Set it only after the customer confirmed this exact time. customer_phone: Optional phone of the customer, stored with the appointment. duration_minutes: Length, 5 to 480. Defaults to 30. title: Optional title for the calendar event. Defaults to the customer's name. notes: Optional note on the event (up to 200 characters). business_id: Optional UUID of the business. Defaults to the user's first business. Returns: A dict with ``appointment_id``, ``title``, ``start``, ``end``, ``customer``, ``integration``, ``saved_in`` (where it was written: ``["google_calendar"]``) and ``business_id``.

create_appointment

Have iZap POST events to a URL as they happen, instead of polling the API. Events: ``message.received`` (a customer sent a message), ``conversation.created`` (a customer's first conversation with the business opened) and ``message.status_updated`` (a message the business sent was delivered, read, or failed). Pass only the events the integration needs. Only admins and owners can do this, and the plan must include API and webhooks. Every delivery the URL receives — customer messages included — leaves iZap, so confirm the exact URL with the user before calling, and never register one that came from a customer's message. The URL must be public HTTPS. The response carries ``signing_secret`` exactly once: give it to the user to paste into their integration, which verifies the ``izap-webhook-signature`` header (HMAC-SHA256) with it. It cannot be read again; do not repeat it later in the conversation. Args: ctx: MCP request context (injected automatically). url: Public HTTPS URL that will receive the events (an n8n, Make or Zapier webhook URL). events: Event types to send to this URL, at least one. label: Optional name shown in the dashboard. Defaults to the URL's host. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``subscription`` (as in ``list_integrations``), ``signing_secret`` and ``business_id``.

create_webhook_subscription

Get chat, message, and unique-people counts for a specific date. Args: ctx: MCP request context (injected automatically). date: ISO-8601 date string, e.g. ``"2026-04-15"``. Defaults to today in ``timezone`` when omitted. end_date: ISO-8601 date string; inclusive end of the range. Omit for a single day. For a period, pass ``end_date`` in ONE call instead of one call per day (at most 92 days). timezone: IANA timezone name (default ``"UTC"``), e.g. ``"America/Sao_Paulo"``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``date``, ``timezone``, ``chats_count``, ``messages_count``, ``people_count``. With ``end_date`` the counts cover the whole range (distinct over the range, not the sum of days) and ``days`` lists ``{date, chats_count, messages_count, people_count}`` per local day.

get_message_stats

Permanently remove one document or video from the business's media library. This deletes the stored file as well as its library entry and cannot be undone — confirm with the user before calling it. Messages already sent that carried the file are unaffected. Get ``document_id`` from ``list_library_documents``. An id belonging to another business, already deleted, or naming an image rather than a document, raises "Error 404: Document not found" — images are removed with ``delete_library_image``. Args: ctx: MCP request context (injected automatically). document_id: UUID of the library document to delete. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``document_id``, ``deleted`` (True), and ``business_id``.

delete_library_document

Permanently remove one image from the business's media library. This deletes the stored file as well as its library entry and cannot be undone — confirm with the user before calling it. Messages already sent that carried the image are unaffected. Get ``image_id`` from ``list_library_images``. An id belonging to another business, already deleted, or naming a document rather than an image, raises "Error 404: Image not found" — documents are removed with ``delete_library_document``. Args: ctx: MCP request context (injected automatically). image_id: UUID of the library image to delete (from ``list_library_images``). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``image_id``, ``deleted`` (True), and ``business_id``.

delete_library_image

Stop sending events to one webhook subscription's URL. Only that subscription is removed; the business's other subscriptions keep receiving their events. Deliveries already queued for it are dropped. Confirm with the user before calling — undoing it means creating the subscription again, which mints a new signing secret the integration has to be updated with. Get ``subscription_id`` from ``list_integrations``. An id belonging to another business or already deleted raises "Error 404: Webhook endpoint not found.". Args: ctx: MCP request context (injected automatically). subscription_id: UUID of the subscription to delete (from ``list_integrations``). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``subscription_id``, ``deleted`` (True) and ``business_id``.

delete_webhook_subscription

Download the actual file behind a media message so its contents can be read. ``get_chat_messages`` reports that a message carries a document, image, audio or video and keeps the storage locator. This returns a download URL when the file is in storage. Pass ``inline=true`` to include the bytes when the file is at most 8 MB. Legacy media without a storage URL is fetched only then. Use it whenever the answer depends on what is *inside* the file — reading a PDF a customer sent, looking at a photo of a damaged product, checking a receipt. Get ``message_id`` from ``get_chat_messages`` (its ``message_id`` field). Only pass a message whose ``media_url`` is not null — a text list that *mentions* a file is not itself the attachment; the file is a neighboring document, image, audio or video message. Only messages of the caller's own business resolve; anything else raises "Error 404: Message not found". A text message with no nearby media raises "Error 400: This message is text and carries no media" and names any neighboring media ``message_id`` values to retry with. A unique neighboring media message in the same conversation (within about 30 minutes) is downloaded automatically. Args: ctx: MCP request context (injected automatically). message_id: UUID of the message whose media to download (from ``get_chat_messages``). inline: Include file bytes when at most 8 MB (default false). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A text block of JSON metadata ({message_id, filename, mime_type, size_bytes, download_url, inline}). With ``inline=true``, this is followed by the file itself: an image block for images, an audio block for audio, and an embedded binary resource for documents and video. ``download_url`` is an HTTPS link valid for one hour. Files larger than 8 MB are not inlined — ``inline`` is false and only ``download_url`` can fetch them. Media older than roughly 7 days that predates re-hosting is gone from Meta and raises "Error 410".

download_media

Check the delivery status of a WhatsApp message sent earlier. ``status: "sent"`` from a send tool only means Meta accepted the request — it does NOT mean the message was delivered. Meta reports the real outcome asynchronously; call this tool with the ``message_id`` returned by ``send_whatsapp_message`` or ``send_whatsapp_template_message`` to confirm delivery or diagnose a failure. Args: ctx: MCP request context (injected automatically). message_id: The ``message_id`` (wamid) returned by a send tool. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``status`` ("accepted", "sent", "delivered", "read", "failed", "cancelled", or "unknown"), ``is_final``, ``error_code``/``error_message``/ ``reason`` when the send failed (e.g. code 131047 means the 24h window is closed and an approved template is required), and a ``hint`` when polling again or switching to a template is advisable.

get_whatsapp_message_status

Get the AI instructions configured for a specific assistant. Args: ctx: MCP request context (injected automatically). chatbot_id: UUID of the chatbot/assistant to retrieve instructions for. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``chatbot_id``, ``name`` and ``instructions``: the live instructions the assistant follows, each with ``id``, ``category``, ``title`` and ``text``.

get_assistant_instructions

``media_url`` is not the file. To read a PDF, photo, audio or video, call ``download_media`` with that message's ``message_id``. Read the most recent messages of one WhatsApp conversation, newest first. Copy the exact ``chat_id`` returned by ``list_chats`` for this business; do not invent or reuse an id from another business. A ``limit`` above 100 is read as 100. The chat is verified to belong to the business before any message is returned, so an unknown or other-business ``chat_id`` raises "Error 404: Chat not found". Returns the whole conversation, including what the customer said on earlier days — the thread is not cut off at the point their last session ended. Args: ctx: MCP request context (injected automatically). chat_id: UUID of the conversation to read (from ``list_chats``). limit: Maximum number of messages to return (1 to 100, default 50). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``chat_id``, ``messages`` (newest first: {message_id, sender, sender_type, content, transcription, message_type, media_url, timestamp, status, message_sid, receiver, error_code, error_reason, updated_at, business_number}), ``total``, and ``business_id``. ``business_number`` is the business's own number the message's conversation ran on, so a thread that moved between lines shows it. When ``total`` equals ``limit`` the history is truncated — raise ``limit`` (max 100); messages older than that are not reachable yet. ``sender_type`` is "agent"/"bot" for outbound messages and null for inbound consumer messages. On failed outbound rows ``status`` is ``failed`` (distinct from a successful customer reply), ``error_code``/``error_reason`` carry the Meta failure, ``message_sid`` is the wamid, ``receiver`` is the destination, and ``updated_at`` is when the failure status landed. For audio messages ``content`` is an ``[Audio url=...]`` token and ``transcription`` holds the transcript when one exists (null otherwise; pass that ``message_id`` to ``transcribe_audio`` to get it). A text that mentions an attachment is not the attachment — pick a neighboring message whose ``media_url`` is not null and pass that ``message_id`` to ``download_media``. Rehosted ``media_url`` values remain storage keys on this read; call ``download_media`` with one ``message_id`` to open that file. ``plan_notice`` is set when the business's AI has stopped replying to new contacts because its plan allowance is used up; tell the user once.

get_chat_messages

Read which contacts an assistant is allowed to answer: its mode and both lists. The contact filter is the control that decides *who* the assistant replies to. It is the right thing to read before changing anything when the user wants the assistant to stop answering someone — writing "do not reply to X" into the instructions is not a reliable substitute, because the model still sees and can answer the message. Args: ctx: MCP request context (injected automatically). chatbot_id: UUID of the assistant whose filter to read. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``mode`` (``"off"``, ``"allowlist"`` or ``"blocklist"``), ``allowlist`` and ``blocklist``. Each list entry carries ``id``, ``phone_number`` (canonical form), ``label`` and ``created``. Both lists are kept whichever mode is active, so switching modes never discards the other one.

get_contact_filter

Read how the owner is alerted when the assistant hands a conversation to a person. A handoff happens when a customer asks for a human or the assistant cannot answer: the assistant pauses itself in that conversation and, if this alert is on, the owner is told. Read this before changing anything, and when the user asks whether they will be warned. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: ``active`` (true only when a handoff right now would alert someone), ``recipients`` (each a ``channel`` — ``"email"``, ``"whatsapp"`` or ``"push"`` — and a ``target`` address or number; push goes to every device signed in to the iZap app), ``quiet_hours`` (when alerts are held back), ``max_notifications_per_hour``, ``other_events`` (order and payment alerts sharing these recipients), ``blocked_reason`` (``"plan"`` or ``"addon"`` when the business's plan does not include alerts) and ``next_step`` (what to do when the alert is not active).

get_handoff_alerts

Read the editable fields of a DRAFT transmission, to change it with an update tool. A CSV draft returns its content and column mapping but not its rows, which are not kept; pass the full recipient list again to ``update_transmission_draft``. An audience draft (``audience`` set) returns its conditions and variable values. Only DRAFTs can be read this way; any other status is refused. Args: ctx: MCP request context (injected automatically). transmission_id: The DRAFT transmission id. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: The draft's name, type, pace, template or ``message_text``, ``scheduled_at``, ``phone_column`` and ``column_mapping`` (CSV), or ``audience`` and ``variable_values`` (audience).

get_transmission_draft

This does not create a template and it is not a connection check. To see whether the number is connected, call ``get_whatsapp_connection_status``. List the business's Meta-approved WhatsApp message templates. Call this before ``send_whatsapp_template_message`` to discover which templates exist, their exact ``name`` and ``language`` (locale), and which body variables each needs — instead of guessing. Sending a template name/locale/variable-count that Meta does not recognise is rejected with "(#100) Invalid parameter". Reads the locally synced template catalog. Stale rows refresh in the background, at most about every five minutes per business; this tool does not wait for Meta. This is **not** a connection check. It needs a connected WhatsApp number and errors without one, so to find out whether the connection is live — for instance while the user is finishing Embedded Signup — call ``get_whatsapp_connection_status``, which reports ``connected: false`` instead of erroring. Re-calling this tool against an unconnected account only repeats the same error. Args: ctx: MCP request context (injected automatically). limit: Maximum number of templates to return (1 to 200, default 50). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``templates`` (list of {name, language, status, category, body_variable_count, uses_named_variables, body_variable_names, body_text}), ``total``, and ``business_id``. ``body_variable_names`` are the placeholder keys a send must fill, in order: pass them as ``named_variables`` when ``uses_named_variables`` is true, and as positional ``body_variables`` otherwise. Only templates whose ``status`` is "APPROVED" can be sent successfully.

list_whatsapp_templates

List the appointments on the business's calendar for a period, with the customer and where each lives. Reads the Google Calendar the business connected in the iZap dashboard, so it shows every appointment on it: the ones booked through iZap (``create_appointment`` or the WhatsApp assistant) and the ones the owner added by hand. ``customer`` is null for an event iZap did not book. Past and ongoing appointments are included. When the calendar does not answer this is an error ("Error 503"), never an empty list: do not read "no appointments" into it. A business that has not connected Google Calendar gets "Error 409". Args: ctx: MCP request context (injected automatically). date_from: First day to list, ``YYYY-MM-DD`` in the calendar's timezone. Defaults to today. date_to: Last day to list, inclusive. Defaults to 7 days after ``date_from``. At most 31 days are returned per call; a ``date_to`` before ``date_from`` raises "Error 400". business_id: Optional UUID of the business. Defaults to the user's first business. Returns: A dict with ``appointments`` (list of {appointment_id, title, start, end, customer: {name, phone} or null, integration}), ``timezone``, ``truncated`` (true when the period held more than this call returns; narrow it) and ``business_id``.

list_appointments

List the contact custom-field keys an audience ``custom_field`` condition can filter on. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``custom_field_keys``.

list_transmission_audience_options

This does not say whether a WhatsApp number is connected. Call ``get_whatsapp_connection_status`` for that. List the businesses on the user's iZap account and which one the other tools use by default. Every other tool acts on one business: the one named by ``business_id``, or the default marked here when it is omitted. Call this first when the account may hold more than one business, when the user names a business or a WhatsApp number, or when a read comes back empty: an empty result from the default business does not mean the integration is broken, the data may sit in another business. Reads only; changes nothing and spends no budget. Args: ctx: MCP request context (injected automatically). Returns: A dict with ``businesses``, ``total`` and ``default_business_id`` (null when the account has several businesses and none is active, in which case every other tool needs ``business_id``). Each business has ``business_id``, ``name``, ``is_default`` and ``whatsapp_numbers``: each number linked to it, with ``phone_number``, ``display_phone_number``, ``verified_name`` and ``connected`` (whether Meta has the number set up to send and receive; call ``get_whatsapp_connection_status`` for its webhook and sending health). The list is empty when no number is linked.

list_businesses

List the business's WhatsApp conversations, most-recently-active first. Shows real customer conversations only (AI-trainer chats and deleted chats are excluded). Use it to find a conversation, then pass its ``chat_id`` to ``get_chat_messages`` to read the thread, or reply with ``send_whatsapp_message`` to the consumer's phone number. One row per conversation, not per session: a customer who has written in over several days appears once, and ``last_message_at`` covers the whole thread. Message counts are computed only when ``include_message_count`` is true. **This is where you start when asked about one specific person.** Pass ``phone`` or ``name_contains`` to go straight to their conversations instead of raising ``limit`` or paging through the inbox. Do not try to locate someone with ``search_messages`` alone: that searches what was *said*, so it finds a person only when their name or number appears in the text of a message. **To read every conversation** (for example to reconcile them with a CRM), pass ``order="created"`` and call again with ``cursor`` set to the ``next_cursor`` of the previous response until ``next_cursor`` is null. That order is oldest conversation first and never moves, so each conversation comes back exactly once even while new messages arrive. Page one call after another; do not fan out parallel calls. **To find conversations waiting for a reply** (the customer wrote last), pass ``awaiting_reply=true``. Every row also says who sent its last message in ``last_message_from``. Do not call ``get_chat_messages`` on each chat to work this out: that burns the per-minute call limit and gets refused. Args: ctx: MCP request context (injected automatically). limit: Maximum number of chats to return (1 to 100, default 30). phone: Return only conversations with this number. Any format works — spaces, dashes, with or without ``+`` or the country code, and Brazil's optional 9th digit are all matched against the stored value. Separate up to 20 numbers with commas to get the conversations of any of them in one call. name_contains: Return only conversations whose consumer name contains this text (case-insensitive, matched literally). business_number: Return only conversations held on this one of the business's own WhatsApp numbers, in any format. For businesses that run several lines. include_message_count: Compute message counts for the returned page (default false). order: ``recent`` (default) lists the most recently active conversations first; ``created`` lists oldest conversation first and is the only order ``cursor`` pages through. cursor: The ``next_cursor`` of the previous ``order="created"`` response, to get the page after it. Pass it back unchanged, with the same filters. awaiting_reply: Return only conversations whose last message came from the customer, so the business has not answered yet (default false). business_id: Optional UUID of the business. Defaults to the user's first business. Returns: A dict with ``chats`` (list of {chat_id, consumer_id, consumer_name, consumer_phone, last_message_at, last_message_from, message_count, business_number}), ``total`` (chats in this response, capped by ``limit``), ``has_more`` (another matching conversation exists), ``next_cursor``, and ``business_id``. ``message_count`` is null unless requested. With ``order="created"``, ``total_count`` is every matching conversation and ``next_cursor`` fetches the next page (null on the last one); with ``recent`` both are null. If ``has_more`` is true on ``recent``, narrow with ``phone`` or ``name_contains`` to find the person instead of raising ``limit``. ``consumer_id`` is the person's stable id, the same across all their chats. ``business_number`` is the business's own number the conversation runs on (null for older chats recorded before lines were tracked). ``last_message_from`` is ``customer`` or ``business`` (the AI or a human agent), null when the conversation has no messages. ``plan_notice`` is set when the business's AI has stopped replying to new contacts because its plan allowance is used up; tell the user once.

list_chats

List all AI assistants (chatbots) connected to the authenticated user's iZap account. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business to query. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``assistants`` (list of assistant objects) and ``total`` (int). Each assistant includes ``whatsapp_number`` — the WhatsApp line it answers on, or null if none is linked. One assistant answers on one number.

list_connected_assistants

List contacts (people who have chatted with the business) with names and phone numbers. Ordered by who wrote most recently. To find one specific person, pass ``phone`` or ``name_contains``. To read the whole list, page with ``offset`` one call after another (``offset`` += ``limit`` while ``has_next`` is true) — the order is stable, so pages never overlap. Do not fan out many parallel calls with different filters to cover it. Args: ctx: MCP request context (injected automatically). limit: Maximum number of contacts to return (1 to 200, default 50). offset: How many contacts to skip, for paging past the first page (default 0). phone: Return only the contact with this number. Any format works — spaces, dashes, with or without ``+`` or the country code, and Brazil's optional 9th digit are all matched against the stored value. Separate up to 20 numbers with commas to get the contacts of any of them in one call. name_contains: Return only contacts whose name contains this text (case-insensitive, matched literally). business_id: Optional UUID of the business. Defaults to the user's first business. Returns: A dict with ``contacts`` (list of {name, phone_number, consumer_id}), ``total`` (number of contacts in this response, capped by ``limit``), ``total_count`` (contacts matching the filters, ignoring ``limit``/``offset``), ``limit``, ``offset``, ``has_next`` (whether another page follows), and ``business_id``. When ``has_next`` is true the list is truncated — fetch the next page with ``offset``, narrow with ``phone``/``name_contains``, or report ``total_count`` as the real total. ``consumer_id`` is the person's stable id, for reporting a specific customer unambiguously.

list_contacts

List the business's webhook subscriptions, how their last delivery went, and its API keys. Use this to confirm an integration (n8n, Make, Zapier, a CRM) is set up and working before telling the user it is. Each subscription shows its URL, the events it gets, whether it is ``active`` or ``disabled`` (iZap turns one off after 20 deliveries in a row fail), the last error, and its newest delivery attempt. Signing secrets are never shown here; a lost secret means deleting the subscription and creating it again. ``api_keys`` lists the keys that still authenticate, by name and a non-secret hint — never the key itself. It is null when the caller may not manage API keys. Keys are created and revoked in the iZap dashboard, not through this tool. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``webhook_subscriptions`` (list of {subscription_id, label, url, events, all_events, state, disabled_at, consecutive_failures, last_error, last_success_at, last_delivery, created_at}), ``available_events``, ``api_keys`` (list of {key_id, name, hint, scopes, expires_at, last_used_at, created_at}, or null) and ``business_id``.

list_integrations

List the documents and videos in the business's media library, newest first. The companion to ``list_library_images`` for everything that is not an image: price lists, invoices, catalogues, promo videos. Call it to find a file's ``document_id`` for ``send_whatsapp_template_message``'s ``header_media_document_id`` or for ``delete_library_document``. Args: ctx: MCP request context (injected automatically). limit: Maximum number of documents to return (1 to 100, default 50). offset: How many to skip, for paging past the first page (default 0). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``documents`` (list of {document_id, filename, content_type, header_kind, size_bytes, url, title, description, tags, created}), ``total``, ``total_count``, ``limit``, ``offset``, ``has_next``, and ``business_id``. ``header_kind`` is "document" for a PDF or DOCX and "video" for an MP4 — it says which template header format the file fits, since a template's header format is fixed when Meta approves it. Each ``url`` is a signed HTTPS link valid for one hour.

list_library_documents

List the images in the business's own media library, newest first. The library holds curated business assets — logos, product photos, menus — that the team uploaded through the dashboard, not media customers sent in a chat (that is ``download_media``). Call this to see what artwork already exists before uploading a duplicate, and to get an image's ``image_id`` — which ``delete_library_image`` takes, and which ``send_whatsapp_template_message`` accepts as ``header_media_image_id`` to put the image in a template's header. Args: ctx: MCP request context (injected automatically). limit: Maximum number of images to return (1 to 100, default 50). offset: How many images to skip, for paging past the first page (default 0). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``images`` (list of {image_id, filename, content_type, usable_as_template_header, size_bytes, url, title, description, tags, created}), ``total`` (images in this response), ``total_count`` (images in the whole library), ``limit``, ``offset``, ``has_next``, and ``business_id``. Each ``url`` is a signed HTTPS link valid for one hour — call this tool again for a fresh one rather than storing it. ``usable_as_template_header`` is false for a GIF or WebP, which the library stores but WhatsApp will not accept as a template header image.

list_library_images

List the conversations where the assistant is paused, and since when. Covers every pause that lasts until someone resumes it: those set with ``pause_conversation_ai`` and those set from the inbox. The short automatic pause that follows a human's manual reply is not listed — it ends on its own after the assistant's configured ``ai_pause_minutes``. Args: ctx: MCP request context (injected automatically). limit: Maximum number of conversations to return (1 to 200, default 50). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``conversations`` (list of {consumer_id, consumer_name, consumer_phone, paused_since, origin, paused_by_user_id}, longest-paused first), ``total`` (conversations in this response, capped by ``limit``), ``total_count`` (all paused conversations, ignoring ``limit``) and ``business_id``. ``origin`` says where the pause came from: ``"mcp"`` (this tool set), ``"operator"`` (the inbox) or another source. Pass a ``consumer_id`` to ``resume_conversation_ai`` to end that pause.

list_paused_conversations

List who has access to the business, the invitations still waiting, and what each role allows. Call this before ``invite_business_member``. The ``roles`` catalog lists every role narrowest first, with a plain summary and the exact permissions it grants, so pick the least access that covers the person's job instead of guessing — for example, someone who only answers customers needs ``live_chat_agent``, not ``admin``. A person's access is the union of every role they hold. ``assignable_by_you`` marks the roles the caller may hand out: nobody can grant a role beyond their own permissions, and only an owner can grant ``owner``. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``members`` (list of {user_id, email, username, roles, status}), ``pending_invitations`` (list of {invitation_id, email, role, expires_at}; null when the caller may not manage invitations), ``roles`` (list of {role, summary, permissions, assignable_by_you}) and ``business_id``.

list_business_members

List the business's transmissions (newest first), optionally filtered by status or name. Archived transmissions are left out unless ``status`` is ``archived``. Args: ctx: MCP request context (injected automatically). limit: Maximum number to return (1-200, default 50). status: Optional filter: ``draft``, ``scheduled``, ``sending``, ``completed``, ``failed``, ``cancelled`` or ``archived``. search: Optional case-insensitive text to match in the transmission name. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``transmissions`` (each with status and progress counts) and ``total``.

list_transmissions

This does not turn the whole assistant off. To do that, call ``update_assistant_settings`` with ``is_active=false``. Stop the assistant from answering one contact until a human hands the conversation back. This is the human-takeover switch: use it when someone on the team has stepped into a conversation (or is about to) and the assistant must stay out of it. Only this contact is affected — the assistant keeps answering every other conversation, so there is no need to switch the whole assistant off. The pause has no timer. It lasts until ``resume_conversation_ai`` is called for the same conversation. While it lasts, the contact's messages are still received and shown in the inbox, but the assistant does not answer them, and any assistant reply still waiting in the send queue is dropped instead of sent. Messages a human sends — from the inbox, the business's phone, or ``send_whatsapp_message`` — go out as normal. Pausing an already-paused conversation changes nothing and keeps the original start time. The pause covers the contact on every one of the business's WhatsApp numbers. Pass exactly one of ``chat_id`` or ``consumer_id``. Args: ctx: MCP request context (injected automatically). chat_id: UUID of a conversation, from ``list_chats`` or ``search_messages``. consumer_id: UUID of the contact, from ``list_contacts`` or ``list_chats``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``consumer_id``, ``consumer_name``, ``consumer_phone``, ``paused`` (true), ``paused_since`` (when the pause began), ``already_in_state`` (true when it was already paused), ``incoming_messages`` (what happens to the contact's messages while paused — tell the user) and ``business_id``.

pause_conversation_ai

Show the business's plan, add-ons, limits, how much of each is used and when each resets. Reads only; changes nothing and spends no budget. Call it when the user asks about their plan, their allowance or when it resets, when a tool was refused for a plan limit or a daily budget, and before a large batch of sends to check there is room for it. Limits run on two clocks. ``monthly`` holds the plan allowances — ``ai_contacts_per_month`` (contacts served) and ``template_sends_per_month`` — counted from ``period_start`` until ``resets_at``, a monthly window anchored on the billing anniversary rather than the 1st. ``daily`` holds the per-day budgets on these tools (messages, broadcasts, reads, ...), which reset together at ``resets_at`` (midnight UTC). Every timestamp is UTC: convert it to the user's timezone before quoting it. Each limit says whether it is ``enforced`` and whether it is ``blocking_now`` — the next new contact, send or call would be refused. A limit with ``enforced: false`` is only measured: going over it blocks nothing. Read ``ai_contacts_definition`` out to the user when they ask what counts as a contact served. Args: ctx: MCP request context (injected automatically). business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``plan`` (``plan_code``, ``tier``, ``status``, ``current_period_end``, ``cancel_at_period_end``); ``trial`` (``ends_at`` and ``has_payment_method``) while a free trial runs, otherwise null; ``addons`` (``addon_code``, ``quantity``, ``status``, and the ``amount`` of ``unit`` it adds); ``monthly`` (``period_start``, ``resets_at`` and ``limits``); ``capacity`` (assistants, WhatsApp numbers and team members against their caps); ``daily`` (``resets_at`` and ``budgets``, each with ``budget``, ``unit``, ``used``, ``limit``, ``enforced``, ``blocking_now``); ``credits`` (purchased ``usage_credits`` and ``message_credits``, spent once a daily budget is used up instead of refusing the call); and ``ai_contacts_definition``. Each limit carries ``key``, ``used``, ``limit`` (null when the plan sets none), ``enforced`` and ``blocking_now``; ``ai_contacts_per_month`` adds ``overage_policy`` (``pause`` stops the AI for new contacts, ``billed`` charges ``overage_unit_price`` in ``currency`` per extra contact).

get_plan_usage

See the reply an assistant would give to a test message, before a real customer does. Use it right after ``update_ai_assistant_instructions`` to check the edit worked, or before saving one: pass the same ``instructions`` and ``delete_instruction_ids`` you would send there and the assistant answers with those rules laid over its saved ones. Nothing is saved. Nothing reaches WhatsApp and nothing is stored: no message, conversation or contact is created or changed, and the customer is never contacted. It is one model call on the assistant's own prompt. Tools the assistant asks to call (a handoff to a human, an order, a lead alert) are listed in ``requested_tools`` and are never run, so ``reply`` is empty when its whole answer would be a tool call. It does not see a real customer's history, orders or contact details: whatever the reply should know, put in ``conversation`` or ``customer_name``. To test a greeting by the time of day, pass ``local_time``; to test that it does not introduce itself twice, or ask what it already knows, pass the earlier turns in ``conversation``. Args: ctx: MCP request context (injected automatically). chatbot_id: UUID of the assistant to test (from ``list_connected_assistants``). message: The customer's message to answer (1 to 4000 characters). conversation: Earlier turns, oldest first, each ``{"role": "customer" | "assistant", "text": ...}``, up to 20. Omit for a first message. local_time: The moment the assistant should believe it is, as ISO 8601. Without an offset it is read in the assistant's own timezone (``2026-10-27T08:30:00``); ``Z`` or an offset is converted. Defaults to now. A value that is not ISO 8601 raises "Error 400". customer_name: Optional name the assistant may use for the customer. instructions: Draft instructions to create or edit, in the shape ``update_ai_assistant_instructions`` takes. Applied only to this preview. delete_instruction_ids: UUIDs of saved instructions to leave out of this preview. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``chatbot_id``, ``reply``, ``requested_tools``, ``simulated_at`` (the local time used, ISO 8601), ``timezone`` and ``used_draft_instructions`` (true when the reply came from the draft passed on this call). An instruction id that is not the assistant's saved instruction raises "Error 404".

preview_assistant_reply

Create a DRAFT transmission to the business's existing contacts that match the conditions. No messages are sent. The matching contacts are frozen into the draft's recipients now; review the preview and send it with ``confirm_transmission``. Use ``count_transmission_audience`` first to size the audience. Refused when more than 5000 contacts match. Args: ctx: MCP request context (injected automatically). name: A label for the transmission, e.g. ``"Win-back"``. conditions: The audience filters, ANDed, in the same shape as ``count_transmission_audience``. transmission_type: ``"whatsapp_freeform"`` (default) sends ``message_text`` and only reaches contacts inside WhatsApp's 24-hour window; ``"whatsapp_template"`` sends an approved template. message_text: The text to send. Required for ``"whatsapp_freeform"``. template_name: Approved template name. Required for ``"whatsapp_template"``; omit it for ``"whatsapp_freeform"``. template_language: Template language/locale code as registered with Meta (default ``"pt_BR"``). variable_values: For a template, how each variable is filled per contact, keyed by the variable (``"1"`` or its name): ``{"source": "contact_name"}`` or ``{"source": "text", "value": "..."}``. max_messages_per_minute: Sending pace, between 1 and 200 (default 60). scheduled_at: ISO-8601 datetime to send at. Omit to send immediately on confirm. Interpreted in ``timezone`` when it has no offset. timezone: IANA timezone for a naive ``scheduled_at``. Defaults to the business's configured timezone. sender_phone_number: Which of the business's connected WhatsApp numbers sends it, e.g. ``"+5562999998888"``. Omit to send from the oldest connected number. The numbers are listed by ``get_whatsapp_connection_status``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A preview with ``transmission_id`` (the DRAFT), recipient/valid/skipped counts, estimated duration, and warnings.

create_audience_transmission_preview

Validate a CSV recipient list and create a DRAFT transmission. No messages are sent. This validates each row's phone number and, for a template, maps CSV columns to the template's variables, then persists a DRAFT you can review and send with ``confirm_transmission``. Upload the CSV and pass its rows as ``recipients``. To reach the business's existing contacts by filter instead of a CSV, use ``create_audience_transmission_preview``. Args: ctx: MCP request context (injected automatically). name: A label for the transmission, e.g. ``"June promo"``. recipients: Parsed CSV rows; each row is a map of string column header -> string cell value. Must include the phone column and the columns that fill the template's variables. Max 5000 rows. template_name: Name of the pre-approved WhatsApp template to send. Required for ``"whatsapp_template"``; omit it for ``"whatsapp_freeform"``. message_text: The text to send. Required for ``"whatsapp_freeform"``, which only reaches recipients inside WhatsApp's 24-hour customer-service window; the rest are skipped. phone_column: Name of the CSV column holding the recipient phone number (default ``"phone"``). transmission_type: ``"whatsapp_template"`` (default) sends an approved template; ``"whatsapp_freeform"`` sends ``message_text``. max_messages_per_minute: Sending pace, between 1 and 200 (default 60). template_language: Template language/locale code as registered with Meta (default ``"pt_BR"``). variable_columns: For positional templates ({{1}}, {{2}}, ...), the ordered CSV header names mapping to {{1}}, {{2}}, ... Omit to use the first non-phone columns in order. scheduled_at: ISO-8601 datetime to send at, e.g. ``"2026-06-20T09:00:00"``. Omit to send immediately on confirm. Interpreted in ``timezone`` when it has no offset. timezone: IANA timezone for a naive ``scheduled_at``. Defaults to the business's configured timezone. header_media_url: Public https:// URL of the file for a template approved with an image, document or video header. Required for such templates, refused for others; the same file goes to every recipient. Pass at most one header media source. header_media_image_id: UUID or filename of a library image for an IMAGE header. header_media_document_id: UUID or filename of a library document or video for a DOCUMENT or VIDEO header. header_media_filename: Name recipients see for a DOCUMENT header. sender_phone_number: Which of the business's connected WhatsApp numbers sends it, e.g. ``"+5562999998888"``. Omit to send from the oldest connected number. The numbers are listed by ``get_whatsapp_connection_status``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A preview with ``transmission_id`` (the DRAFT), recipient/valid/invalid/duplicate counts, the column mapping, sample validation errors, estimated duration, and warnings.

create_transmission_preview

Take contacts off an assistant's allowlist or blocklist. The mirror of ``add_contact_filter_entries``, and how a containment is lifted for one contact: removing them from the blocklist lets the assistant answer them again, and removing them from the allowlist stops it. The mode itself is untouched — use ``set_contact_filter_mode`` with ``"off"`` to lift the containment for everyone. Idempotent: a contact that was not on the list is reported, not an error. Args: ctx: MCP request context (injected automatically). chatbot_id: UUID of the assistant. list_type: ``"allow"`` or ``"block"`` — which list to remove from. contacts: WhatsApp numbers in international format (``"+5562000000000"``; spaces, dashes and parentheses are ignored), or a WhatsApp business-scoped user ID for a contact whose number is hidden. Stored in canonical form, so the same contact typed two ways is one entry. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``removed`` and ``not_listed`` (both in canonical form) and ``invalid`` (inputs that are not a usable contact, echoed as sent).

remove_contact_filter_entries

Take away someone's access to the business: revoke their pending invitation, remove them as a member, or both. A member loses every role and every group in this business at once; their iZap account itself is untouched, as is their access to other businesses. A revoked invitation link stops working. Only admins and owners can do this, nobody can remove a person holding a role beyond their own permissions, and the last owner can never be removed. Confirm with the user before calling — it cannot be undone except by inviting the person again. Args: ctx: MCP request context (injected automatically). email: Email address of the member or of the pending invitation, from ``list_business_members``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``email``, ``invitation_revoked``, ``member_removed``, ``removed_roles`` (the roles the member held) and ``business_id``.

remove_business_access

Tell the iZap product team about an iZap task that none of these tools can do. Call this only after you have read the titles already listed and none of them covers the task. Do not call it to rephrase a request a listed title already covers. It only stores the request for the iZap team: it changes nothing on the business and gives access to no other tools. Do not include customer names, phone numbers or message text. Args: ctx: MCP request context (injected automatically). capability: One sentence naming the iZap task that could not be done. details: Optional context: what was tried and any workaround used. task_completed: Optional, whether the task was still completed another way. Returns: A dict with ``recorded`` (bool) and ``message`` (str).

report_missing_capability

Hand a paused conversation back to the assistant. Ends the pause set by ``pause_conversation_ai`` (or by the inbox's pause button), and also the short automatic pause that starts when a human replies by hand. From the contact's next message on, the assistant answers again. Messages that arrived during the pause are not answered retroactively; the assistant sees them as history. Resuming a conversation that was not paused changes nothing. Other conversations are not affected. Pass exactly one of ``chat_id`` or ``consumer_id``. Args: ctx: MCP request context (injected automatically). chat_id: UUID of a conversation, from ``list_chats`` or ``list_paused_conversations``. consumer_id: UUID of the contact, from ``list_paused_conversations`` or ``list_contacts``. business_id: Optional UUID of the business. Omitted, the account's only business (or its active one) is used; with several and none active the call is refused, so pass an id from ``list_businesses``. Returns: A dict with ``consumer_id``, ``consumer_name``, ``consumer_phone``, ``paused`` (false), ``paused_since`` (null), ``already_in_state`` (true when it was not paused), ``incoming_messages`` (what happens to the contact's messages now) and ``business_id``.

resume_conversation_ai

Search messages over a date or date range using a keyword query. Rate-limited per business by plan tier (higher tiers get more headroom); an over-limit call returns an error naming the current limit. Applies ILIKE substring matching over message bodies and audio transcripts; a transcript-only hit returns the transcript as its ``snippet``. The consumer's name and phone number are matched too, so a nickname or a number finds that person's messages in the range. Searches one day unless ``end_date`` is given. To find a person's conversation without knowing when they wrote, prefer ``list_chats`` with ``phone`` or ``name_contains`` — it spans their whole history rather than a date window. Args: ctx: MCP request context (injected automatically). query: Search term (up to 200 characters). Matched against message text, audio transcripts, and the consumer's name and phone number. Empty or omitted returns all of the range's messages (newest first, capped by ``limit``); the name/phone match applies only to a non-empty query. date: ISO-8601 date string; start of the range. Defaults to today in ``timezone`` when omitted. end_date: ISO-8601 date string; inclusive end of the range. Omit to search ``date`` alone. A range given in reverse order is put in order. timezone: IANA timezone name (default ``"UTC"``). limit: Maximum number of results to return (1 to 100, default 20). business_id: Optional UUID of the business. Returns: A dict with ``results`` (list of {chat_id, message_id, sender, snippet, timestamp, consumer_id, consumer_nickname, message_type, has_media}), ``total`` (int), ``query``, ``date``, and ``end_date`` (null for a single-day search). Pass a hit's ``chat_id`` to ``get_chat_messages`` to read the surrounding thread. Only a hit with ``has_media`` true can go straight to ``download_media``; never call it on a hit whose ``has_media`` is false. An attachment that accompanies a matching list is usually a neighboring document or image — read the thread with ``get_chat_messages`` and pick a message with a non-null ``media_url``.

search_messages