langchain-claw-messenger 0.1.0

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

Claw Messenger for LangChain

Use this package to send one controlled plain-text message from LangChain 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 general conversation store. An accepted, delivered, or read outbound status is not proof that the two-way setup works. The controlled reply must reach the tool before it returns proof_status: reply_received.

Install

Install the public package from PyPI:

python3 -m pip install langchain-claw-messenger

Credentials

Set your API key outside code, notebooks, screenshots, 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

import os

from langchain_claw_messenger import create_claw_messenger_tool

tool = create_claw_messenger_tool()
result = tool.invoke(
    {
        "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"
}

The named reply observation point for this proof is the active LangChain tool invocation. Do not count accepted, delivered, or read outbound status as reply proof.

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 LangChain app, use await tool.ainvoke(...). The synchronous invoke path deliberately refuses to nest another event loop.

Agent use

Bind the returned StructuredTool to the LangChain model or agent runtime you already use:

tools = [create_claw_messenger_tool()]

# Bind `tools` to your existing LangChain model or agent runtime.
# Instruct the agent to use only a registered recipient and to call setup
# complete only when proof_status is reply_received.

The tool reads CLAW_API_KEY by default. You can instead pass api_key= at construction time, but never put a real key in source control.

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 or webhook for persistent inbound handling.

Release verification

Each release must pass the same checks used by the n8n and CrewAI 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, 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 LangChain 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