crewai-claw-messenger 0.1.0

Send one controlled Claw Messenger message from CrewAI and prove the matching reply in the tool

Claw Messenger for CrewAI

Use this package to send one controlled plain-text message from CrewAI to a registered E.164 phone and prove the same thread works when the matching reply reaches the active tool invocation.

It is intentionally not a persistent inbound listener, webhook server, delivery guarantee, group-messaging tool, or broad CrewAI toolkit. An accepted, delivered, or read outbound status is not proof that the two-way setup works. The controlled reply must reach this tool, or a separately named WebSocket consumer, webhook, or backend, before the setup counts as proven.

Install

Install the public package from PyPI:

python3 -m pip install crewai-claw-messenger

Credentials

Set your API key outside code, notebooks, screenshots, agent traces, and logs:

export CLAW_API_KEY="cm_live_REDACTED"
export CONTROLLED_TEST_PHONE_E164="[phone]"

For a release proof, use a regenerated key for a test tenant and revoke it when the run is complete.

Quick controlled proof

Prove the tool directly before giving it to an agent:

import os

from crewai_claw_messenger import ClawMessengerTool

tool = ClawMessengerTool()
result = tool.run(
    recipient_e164=os.environ["CONTROLLED_TEST_PHONE_E164"],
    message="This is my Claw Messenger test. Reply yes.",
    timeout_seconds=300,
)
print(result)

The person holding the controlled phone must reply in the same thread while the tool is waiting. Count the run as successful only when the returned JSON includes:

{
  "proof_status": "reply_received",
  "reply_source": "controlled_recipient"
}

Possible proof states are:

• reply_received: the matching reply reached this tool invocation.
• send_failed: Claw Messenger rejected or failed the outbound request.
• reply_timeout: no matching reply reached this invocation before its deadline.
• configuration_error: the key, recipient, message, or timeout was invalid.

In an async host, use await tool.arun(...). The synchronous run path deliberately refuses to nest another event loop.

Minimal crew flow

After the direct proof works, add the same tool to one narrow agent and task:

import os

from crewai import Agent, Crew, Task
from crewai_claw_messenger import ClawMessengerTool

tool = ClawMessengerTool()
agent = Agent(
    role="Messaging test agent",
    goal="Prove one controlled Claw Messenger thread",
    backstory=(
        "Only report success when the tool returns proof_status reply_received. "
        "Accepted, delivered, or read is not reply proof."
    ),
    tools=[tool],
)
task = Task(
    description=(
        "Use the Claw Messenger tool to send one test to {controlled_phone}. "
        "Wait for the controlled reply and return the sanitized tool result."
    ),
    expected_output="A sanitized proof result or a clear timeout or send failure.",
    agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
print(crew.kickoff(inputs={"controlled_phone": os.environ["CONTROLLED_TEST_PHONE_E164"]}))

Tell the agent to use only a registered recipient the operator controls and to call setup complete only when proof_status is reply_received.

Current scope

• One plain-text outbound message to one registered E.164 recipient.
• Truthful send.result status fields.
• One matching inbound reply observed during the same tool call.
• Sanitized message and chat identifier hints rather than raw identifiers.

The tool stops listening when it returns. Use your own long-running WebSocket consumer, webhook, or backend for persistent inbound handling, and name that observation point before a controlled proof run.

Release verification

Each release must pass the same checks used by the n8n and LangChain packages:

1. Keep the package metadata and bundled LICENSE file on the approved Apache 2.0 license.
2. Use package-scoped PyPI publisher access without placing credentials in the repository, examples, agent traces, screenshots, or logs.
3. Regenerate a test-tenant API key specifically for this proof. Never reuse a production key.
4. Name one controlled registered E.164 phone, a person ready to reply, and the active CrewAI tool invocation as the reply observation point.
5. Build, test, check, and install the wheel in a clean virtual environment.
6. Send one short plain-text message, then reply once from the controlled phone in the same thread while the tool is waiting.
7. Retain only sanitized evidence showing proof_status: reply_received for the matching thread. Accepted, delivered, or read outbound status alone does not pass this gate.
8. Revoke the regenerated test key.
9. Publish only after explicit approval. Release notes and maintainer contact remain separate decisions.

Claw Messenger documentation: https://clawmessenger.com/docs