Skip to content
SocialMate

SocialMate – Messaging & AI Agent · More

Developer API

Register your own tools, packs and events.

Any plugin can offer the Claude Agent its own tools (things the agent may look up or do) and events (things that happened, which the owner can turn into a message or an agent task) through a small public API. The site owner then sees your tools under Agent → What it may do and your events on the Events tab, and decides who may use what — exactly as for the built-in ones. These function names are stable.

Before you start

  • The plugin active. Check with function_exists('socialmate_agent_register_tool') — it is defined as soon as the plugin loads; socialmate_agent_loaded fires once it has booted.
  • A complete, copyable example ships with the plugin: examples/real-estate-pack.php.
  • No server needed Tools also work from any MCP client with an access key; events need the Claude Agent (Pro).

Register a tool

Register inside the socialmate_agent_register_tools action (registering earlier also works — it is checked when the list is built; later returns a WP_Error). socialmate_agent_register_tool() returns true or a WP_Error with the reasons, and a refused tool is listed under Tools → Refused tools.

<?php
// In your own plugin. Runs when SocialMate builds its tool list.
add_action('socialmate_agent_register_tools', static function (): void {
    if (!function_exists('socialmate_agent_register_tool')) {
        return; // SocialMate – Messaging & AI Agent is not active.
    }

    socialmate_agent_register_tool('acme_opening_hours', [
        'label'        => 'Opening hours',
        'description'  => 'Opening hours of each branch for a given day. Returns branch, opens and closes.',
        'lanes'        => ['customer', 'owner'],   // who may use it
        'effect'       => 'read',                  // read | act
        'input_schema' => [
            'type'                 => 'object',
            'additionalProperties' => false,
            'properties'           => [
                'branch' => ['type' => 'string', 'maxLength' => 60],
                'day'    => ['type' => 'string', 'description' => 'YYYY-MM-DD, default today'],
            ],
        ],
        // Any array is returned to the agent as JSON; a string as text; a WP_Error as an error.
        'handler' => static function (array $args, $ctx) {
            return ['branch' => $args['branch'] ?? 'Main street', 'opens' => '09:00', 'closes' => '18:00'];
        },
    ]);
});

Definition keys

  • label — Name shown to the site owner.
  • description — Required. What the model reads to decide when to use the tool.
  • input_schema — A JSON Schema of type object with additionalProperties: false. Arguments are validated against it before your handler runs.
  • lanes — customer and/or owner. Default: owner only.
  • effect — read (default) or act (changes something).
  • risk — low, medium or high. Default: low for reads, medium for acts.
  • identity — customer when the tool works on the caller’s own records (read who they are from socialmate_agent_context()).
  • caps — WordPress capabilities the owner’s mapped user must have.
  • default_on — Starts on? Default: yes for reads, no for acts.
  • never_unattended — true makes it always ask the owner first.
  • timeout_ms — 1000–20000, default 8000.
  • handler — callable(array $args, $ctx). Return a string, an array (sent as JSON) or a WP_Error.
  • prepare — For acts: callable(array $args, $ctx) returning ['resolved' => …, 'summary' => …] — what will happen, shown to the owner for approval; the handler then gets resolved.
  • pack — Optional group slug for socialmate_agent_register_tool(); without it the tool is listed under Other plugins.

Rules enforced at registration

  • Names are snake_case, 2–48 characters (^[a-z][a-z0-9_]{1,47}$), and should carry your own prefix. Built-in tool names are reserved.
  • A customer-lane tool may not accept identity or recipient arguments — among them to, phone, phone_number, mobile, whatsapp, chat_id, jid, recipient(s), user_id, customer_id, email, email_address, account_id — nor ones like media_id, path, file, sql, endpoint, webhook, callback_url.
  • A customer tool that takes a personal record id (order_id, booking_id…) must declare identity: customer and scope itself to the caller — or stay owner-only.
  • A high-risk customer act must set never_unattended. Some kinds of tool are never exposed at all (names about SQL, passwords, API keys, plugins, themes, roles, refunds and the like).
  • Acts start off until the site owner turns them on, and can be held for approval.

An action for the customer in the chat

<?php
// Inside the same socialmate_agent_register_tools callback.
// A customer ACT scoped to the person in the chat. It takes no phone, email or
// customer id: who the customer is comes from socialmate_agent_context().
socialmate_agent_register_tool('acme_request_callback', [
    'label'        => 'Request a call back',
    'description'  => 'Ask the office to call the customer back about a topic at a preferred time.',
    'lanes'        => ['customer'],
    'effect'       => 'act',
    'risk'         => 'medium',
    'identity'     => 'customer',
    'input_schema' => [
        'type'                 => 'object',
        'additionalProperties' => false,
        'required'             => ['topic'],
        'properties'           => [
            'topic' => ['type' => 'string', 'maxLength' => 120],
            'when'  => ['type' => 'string', 'maxLength' => 40],
        ],
    ],
    // Resolve exactly what will happen. With "Ask me first" the owner approves THIS summary.
    'prepare' => static fn (array $args) => [
        'resolved' => $args,
        'summary'  => 'Call-back request: ' . $args['topic'] . (isset($args['when']) ? ' at ' . $args['when'] : ''),
    ],
    'handler' => static function (array $args) {
        $ctx = socialmate_agent_context();     // lane, contactPhone (E.164), agentId, job …
        // acme_crm_add_callback($ctx->contactPhone, $args['topic'], $args['when'] ?? '');
        return 'Call-back requested. The office will ring you.';
    },
]);

socialmate_agent_context() returns the run context while your handler runs (null outside a tool call): lane (customer or owner), contactPhone (E.164, set by SocialMate’s signed request — trust this, never an argument), agentId, job, runId, actingUserId and dryRun. Customer-lane handlers run with no WordPress user logged in; owner-lane handlers run as the owner’s mapped user.

Register a pack (tools + events)

socialmate_agent_register_pack() shows your tools as one group card under Agent → What it may do, with your own label, and adds your events to the Events tab. detect decides whether the pack is active on this site. Event definitions can carry label, description, facts (the fields the agent gets), job (the default agent job) and example / example_owner (suggested instructions).

<?php
add_action('socialmate_agent_register_tools', static function (): void {
    if (!function_exists('socialmate_agent_register_pack')) {
        return;
    }

    socialmate_agent_register_pack('recrm', [
        'label'  => 'Real-estate CRM',
        'blurb'  => 'Customers can search listings and request viewings; you can see leads.',
        'icon'   => 'globe',
        'detect' => static fn () => class_exists('My_Crm'),   // the card shows only when true
        'tools'  => [
            'recrm_find_listings' => [
                'label'        => 'Find listings',
                'description'  => 'Search available properties by area, budget and bedrooms.',
                'lanes'        => ['customer', 'owner'],
                'effect'       => 'read',
                'input_schema' => [
                    'type' => 'object', 'additionalProperties' => false,
                    'properties' => [
                        'area'      => ['type' => 'string', 'maxLength' => 80],
                        'max_price' => ['type' => 'number', 'minimum' => 0],
                        'bedrooms'  => ['type' => 'integer', 'minimum' => 0, 'maximum' => 10],
                    ],
                ],
                'handler' => static fn (array $args) => ['listings' => my_crm_search($args)],
            ],
            'recrm_new_leads' => [
                'label'        => 'New leads',
                'description'  => 'Leads created in the last N days with their status.',
                'lanes'        => ['owner'],
                'effect'       => 'read',
                'caps'         => ['edit_posts'],              // checked against the owner's WordPress user
                'input_schema' => ['type' => 'object', 'additionalProperties' => false,
                    'properties' => ['days' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 90]]],
                'handler'      => static fn (array $args) => ['leads' => my_crm_leads($args['days'] ?? 7)],
            ],
        ],
        // Events this pack can send; each appears on the Events tab (Other plugins), ready to be a message or an agent task.
        'events' => [
            'recrm.viewing_tomorrow' => [
                'label'       => 'Viewing tomorrow',
                'description' => 'A viewing starts in about 24 hours. The number comes from the lead.',
                'facts'       => ['listing', 'starts'],
                'job'         => 'custom',
                'example'     => 'Remind them of the viewing time and address, and ask them to reply if they cannot make it.',
            ],
        ],
    ]);
});

Send an event

socialmate_agent_emit( string $type, array $subject, array $facts, array $opts = [] ): int sends a site event on to whatever the owner chose for it on the Events tab — a message they wrote, or an agent task for SocialMate. The recipient is $subject['phone'] from your own record — never chosen by a model.

<?php
// When the viewing reminder is due (your cron, your hook):
$queued = socialmate_agent_emit(
    'recrm.viewing_tomorrow',
    ['phone' => $lead->phone, 'name' => $lead->first_name],          // the recipient, from YOUR record
    ['listing' => $listing->title, 'starts' => $viewing->start],     // only what the agent needs; no secrets
    ['object_id' => $viewing->id, 'transition' => 'reminder-24h']    // "once per record" de-duplication
);
// $queued = how many messages or agent tasks were queued (0 while the owner has this event off).
  • $subject: phone (required for customer jobs), optional name and locale.
  • $opts: object_id and transition (a job set to “once per record” sends once per record and transition), consent as ['source' => …, 'at' => unix time] when the person opted in (jobs that require opt-in skip events without it), and visitor => true when a website visitor caused it (then the once-a-day-per-number limit applies).
  • Facts are capped in size; send only what the agent needs, never secrets.

Hooks

<?php
// Adjust what an event sends, or return false to send nothing.
add_filter('socialmate_agent_event_payload', static function (array $facts, string $type, array $subject) {
    unset($facts['internal_note']);
    return $facts;
}, 10, 3);

// After every tool call (audit, analytics).
add_action('socialmate_agent_tool_called', static function (string $tool, $ctx, $result): void {
    // $ctx->lane, $ctx->source; $result->status
}, 10, 3);

// Messages: teach STOP / START another word (added to the built-in list, never replacing it).
add_filter('socialmate/consent/stop_words', static fn (array $words) => array_merge($words, ['baja']));

Good to know

Test without WhatsApp. Every tool has a Test drawer under Agent → What it may do (with Dry run for acts), and the same tool is callable over the MCP endpoint with an access key.

  • Plugins that register WordPress Abilities (WordPress 6.9+) are picked up automatically, without this API; they start off and are grouped under the plugin.
  • Any plugin’s own do_action() hooks can already be a message or an agent task from the Events tab (Other plugins). Use socialmate_agent_emit() when you want a named event with known details and a known customer number.
  • The owner’s per-tool settings always win over your defaults.

Next

Your store, on WhatsApp, from your own number.

Install the free plugin, connect it to SocialMate with one token, and choose what should happen for each event. Messages work on every plan; the Claude Agent comes with Pro.

Free forever · no card Download free