NV oOS Pro Toolkit Communications

The Pro Toolkit Communications system provides multi-channel messaging infrastructure built on WordPress Custom Post Types. It manages the full communication lifecycle: contact discovery → message composition → delivery tracking → thread history. All entities are stored as CPT records accessible via the toolkit_cpt MCP tool.

WP-CLI Commands

Key mcp-ai WP-CLI commands for communications operations. Run via terminal:

Command	Use for
wp mcp-ai cron	Verify message delivery cron jobs, check retry schedules
wp mcp-ai queue	Inspect outbound message queue, retry failed deliveries
wp mcp-ai health	Validate channel configuration (SMS gateway, email SMTP, WhatsApp API)
wp mcp-ai log	View message delivery logs, troubleshoot delivery failures

When to use this skill

Trigger when ANY of the following is true:

• Viewing, searching, or filtering channel messages or contacts.
• Creating or updating contact profiles with channel handles (SMS, email, WhatsApp).
• Sending or tracking outbound messages across any channel.
• Reviewing inbound messages and routing them to the appropriate team or agent.
• Troubleshooting message delivery status (sent → delivered → read → failed).
• Managing media attachments on messages (images, documents, audio).
• Building communication threads — linking related messages by contact or context.
• Searching for all messages from a specific contact or across a date range.
• Checking a contact's last seen timestamp or communication history.
• Linking a channel contact to a WordPress user account.

Mental model — Communications entities and lifecycle

The communications system is organized around two core entities linked by contact:

CONTACT ──(has many)──→ MESSAGES
   │                       │
   ├── user_id (WP user)   ├── direction (inbound/outbound)
   ├── channel             ├── status (sent/delivered/read/failed)
   ├── handle              ├── media_ids (attachments)
   └── last_seen           └── contact_id (link back)

Relationships:

• A Contact (mcp_chan_contact) represents a person on a specific channel. One person may have multiple contacts (e.g., SMS at one number, WhatsApp at another).
• A Message (mcp_chan_message) is always associated with exactly one contact via _chan_msg_contact_id. The direction indicates inbound (from contact) or outbound (to contact).
• A Contact can be linked to a WordPress user via _chan_contact_user_id, enabling authenticated, role-aware communication.
• Media attachments are stored as an array of WordPress attachment IDs in _chan_msg_media_ids.

Communications Entity Types

All communications entities are managed through the toolkit_cpt MCP tool. Use the appropriate post_type slug for each entity:

CPT Slug	Label	Purpose	Key Meta Fields
mcp_chan_message	Channel Messages	Individual messages across all channels with delivery tracking	_chan_msg_contact_id, _chan_msg_direction, _chan_msg_status, _chan_msg_media_ids
mcp_chan_contact	Channel Contacts	Contact profiles per channel with handle and user linking	_chan_contact_user_id, _chan_contact_channel, _chan_contact_handle, _chan_contact_last_seen

Channel Message Meta Fields (detailed)

Field	Type	Description	Example / Enum
_chan_msg_contact_id	integer	Post ID of the associated contact	42
_chan_msg_direction	string	Message direction	"inbound", "outbound"
_chan_msg_status	string	Delivery/read status	"sent", "delivered", "read", "failed"
_chan_msg_media_ids	array	WordPress attachment IDs for media	[123, 456]

Message status lifecycle:

draft → sent → delivered → read
                ↘ failed (with retry)

Channel Contact Meta Fields (detailed)

Field	Type	Description	Example / Enum
_chan_contact_user_id	integer	WordPress user ID (0 if unlinked)	1
_chan_contact_channel	string	Communication channel	"sms", "email", "whatsapp"
_chan_contact_handle	string	Contact address on the channel	"+15551234567", "user@example.com"
_chan_contact_last_seen	string	ISO 8601 timestamp of last activity	"2026-08-12T14:30:00+00:00"

Available Tools

All communications operations use the toolkit_cpt MCP tool. This is the single interface for all communications CRUD operations.

Discovery

# List all available communications post types
toolkit_cpt(action: "list_types")

# Get field schema for messages or contacts
toolkit_cpt(action: "get_schema", post_type: "mcp_chan_message")
toolkit_cpt(action: "get_schema", post_type: "mcp_chan_contact")

Reading records

// List recent messages (most recent first)
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_chan_message",
    "orderby": "date",
    "order": "DESC",
    "per_page": 20,
    "page": 1
  }
}

// Find messages for a specific contact
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_chan_message",
    "filters": [
      { "key": "_chan_msg_contact_id", "value": "42" }
    ]
  }
}

// Find contacts by channel type
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_chan_contact",
    "filters": [
      { "key": "_chan_contact_channel", "value": "whatsapp" }
    ]
  }
}

// Search contacts by handle (phone number or email)
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "list_items",
    "post_type": "mcp_chan_contact",
    "search": "+15551234567"
  }
}

// Get a single message or contact
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "get_item",
    "post_type": "mcp_chan_message",
    "item_id": 789
  }
}

Creating records

// Create a new contact
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_chan_contact",
    "fields": {
      "title": "Alice Chen - WhatsApp",
      "_chan_contact_user_id": 5,
      "_chan_contact_channel": "whatsapp",
      "_chan_contact_handle": "+15559876543",
      "_chan_contact_last_seen": "2026-08-12T10:00:00+00:00"
    }
  }
}

// Create an outbound message with media attachments
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_chan_message",
    "fields": {
      "title": "Order confirmation #1042",
      "content": "Hi Alice, your order has shipped! Track it here: https://track.example.com/1042",
      "_chan_msg_contact_id": 42,
      "_chan_msg_direction": "outbound",
      "_chan_msg_status": "sent",
      "_chan_msg_media_ids": [301, 302]
    }
  }
}

// Log an inbound message
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "create_item",
    "post_type": "mcp_chan_message",
    "fields": {
      "title": "Inquiry about return policy",
      "content": "What's your return window for electronics?",
      "_chan_msg_contact_id": 42,
      "_chan_msg_direction": "inbound",
      "_chan_msg_status": "delivered"
    }
  }
}

Updating records

// Update message delivery status
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_chan_message",
    "item_id": 789,
    "fields": {
      "_chan_msg_status": "read"
    }
  }
}

// Update contact's last seen timestamp
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_chan_contact",
    "item_id": 42,
    "fields": {
      "_chan_contact_last_seen": "2026-08-12T14:45:00+00:00"
    }
  }
}

// Link a contact to a WordPress user
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "update_item",
    "post_type": "mcp_chan_contact",
    "item_id": 42,
    "fields": {
      "_chan_contact_user_id": 12
    }
  }
}

Deleting records

// Delete a message (permanent)
{
  "name": "toolkit_cpt",
  "arguments": {
    "action": "delete_item",
    "post_type": "mcp_chan_message",
    "item_id": 789
  }
}

⚠️ Warning: Deleting a message is permanent. Consider archiving via status change or using update_item to set a custom field instead, to preserve the communication thread for audit purposes.

Common Workflows

Contact onboarding workflow

1. Receive first message:  Identified via channel webhook or manual entry.
2. Search for existing:    list_items(mcp_chan_contact, search: "<handle>")
3. If new contact:         create_item(mcp_chan_contact, with channel, handle, user_id)
4. If existing contact:    update_item(mcp_chan_contact, last_seen timestamp)
5. Log message:            create_item(mcp_chan_message, direction: "inbound", contact_id)
6. Link to WP user:        update_item(mcp_chan_contact, _chan_contact_user_id) if authenticated

Message thread view

1. Find contact:       list_items(mcp_chan_contact, search: "<phone or email>")
2. Get all messages:   list_items(mcp_chan_message,
                         filters: [{key: "_chan_msg_contact_id", value: "<contact_id>"}],
                         orderby: "date", order: "ASC", per_page: 50)
3. Review thread:      Messages are sorted chronologically. Check status for delivery issues.

Delivery troubleshooting

1. Find failed messages:  list_items(mcp_chan_message,
                            filters: [{key: "_chan_msg_status", value: "failed"}])
2. Check contact:         get_item(mcp_chan_contact, item_id: <contact_id>)
3. Verify channel:        Confirm _chan_contact_channel and _chan_contact_handle are valid.
4. Retry or escalate:     If handle is correct, check gateway config with wp mcp-ai health.
                          If handle is invalid, update contact with corrected handle.

Multi-channel contact deduplication

1. Search all contacts:   list_items(mcp_chan_contact, search: "<name or handle>")
2. Check for duplicates:  Same person may appear under sms, email, and whatsapp.
3. Link to WP user:       If the person has a WP account, set _chan_contact_user_id
                          on ALL their contact records to unify identity.
4. Cross-reference:       Use _chan_contact_user_id to find all contacts for a user.

Critical Rules

• Always use get_schema first before creating or updating a record to verify available field keys and types.
• _chan_msg_contact_id is required for every message — never create an orphaned message without a contact link.
• Message status transitions are directional — sent → delivered → read. Never skip statuses; each transition should be observable.
• _chan_contact_handle must be globally unique per channel — two contacts cannot share the same handle on the same channel type.
• _chan_contact_user_id is 0 for unlinked contacts — do not leave it null or unset.
• _chan_msg_media_ids is a JSON array — always pass as [301, 302], not a comma-separated string.
• _chan_contact_last_seen uses ISO 8601 — always include timezone offset (e.g., "2026-08-12T14:30:00+00:00").
• Inbound messages should NOT be created manually in production — they arrive via channel webhooks. Manual creation is for testing and data migration only.
• Failed messages can be retried — before retrying, verify the contact handle and channel configuration are valid.

Common Mistakes

WRONG — creating a message without a contact link
{ "action": "create_item", "post_type": "mcp_chan_message",
  "fields": { "title": "Hello", "content": "Hi there!", "_chan_msg_status": "sent" } }
// Missing _chan_msg_contact_id — the message is orphaned.

RIGHT — always link messages to a contact
{ "action": "create_item", "post_type": "mcp_chan_message",
  "fields": { "title": "Hello", "content": "Hi there!", "_chan_msg_contact_id": 42,
  "_chan_msg_direction": "outbound", "_chan_msg_status": "sent" } }

WRONG — skipping delivery status lifecycle
// Setting _chan_msg_status directly to "read" when the message was just created.
// The status flow must follow: sent → delivered → read.

RIGHT — progress status through each stage
1. create_item: _chan_msg_status: "sent"
2. update_item: _chan_msg_status: "delivered"  (gateway confirms delivery)
3. update_item: _chan_msg_status: "read"       (contact opens message)

WRONG — duplicate contact handles on the same channel
// Two contacts with _chan_contact_channel: "sms" and _chan_contact_handle: "+15551234567"
// This creates ambiguity about which contact thread a message belongs to.

RIGHT — search before creating, update instead of duplicating
1. list_items(mcp_chan_contact, search: "+15551234567")
2. If found: update_item to refresh last_seen. If not found: create_item.

WRONG — using non-ISO 8601 timestamps for last_seen
// "2026-08-12 14:30" or "Aug 12, 2026" — these won't sort or compare correctly.

RIGHT — always use ISO 8601 with timezone
// "_chan_contact_last_seen": "2026-08-12T14:30:00+00:00"

WRONG — passing media IDs as a string
// "_chan_msg_media_ids": "301,302" — this won't deserialize as an array.

RIGHT — pass media IDs as a JSON array
// "_chan_msg_media_ids": [301, 302]

Cross-References

• Run design-crm to link communication threads to CRM leads, deals, and customers.
• Run design-email-marketing for bulk email campaign sending and sequence design.
• Run design-social-publishing for social media channel publishing (separate from 1:1 channel messaging).
• Run design-pro-workflow-builder to automate communication workflows (auto-reply, routing, escalation).
• Run wp-security-audit on any message handling code — communications data may contain PII and must be access-controlled.

What This Skill Does NOT Cover

• Email marketing campaigns and newsletter sequences — use design-email-marketing.
• Social media publishing (Twitter/X, Facebook, Instagram, LinkedIn) — use design-social-publishing.
• Gmail inbox integration — use search_gmail for Gmail-specific queries.
• Channel gateway configuration (Twilio, WhatsApp Business API, SMTP) — this is infrastructure-level setup, not CPT data management.
• Real-time message delivery — the toolkit_cpt tool manages records. Actual message transport is handled by the channel gateway and WordPress Action Scheduler.
• Message templating and variable substitution — use design-pro-workflow-builder for message template workflows.