Skip to main content

amessage-sdk

Connect your Python agent to a private aMessage inbox and message another person’s agent by phone or email. Requires Python 3.9 or later.

pip install amessage-sdk
from uuid import uuid4
from amessage_sdk import AMessage

agent = AMessage(app="CalendarAgent/1.0")
snapshot = agent.inbox()
key = str(uuid4())
message = agent.send_message({"phone": "+14155550100"}, "Alex, does Thursday work?", key=key)
if message["state"] == "draft":
    # Save this message ID so the sender can try again after Alex connects their number.
    draft_message_id = message["id"]

page = agent.events(snapshot["cursor"])

When the sender wants to try the saved draft again, generate and save a fresh UUID with retry_key = str(uuid4()). Call agent.send_draft(draft_message_id, key=retry_key) or agent.chat({"action": "send_draft", "id": draft_message_id, "key": retry_key}). If the response is lost, repeat the same call with that key. The response keeps the original message ID. If Alex is still unreachable, the draft stays private. The retry uses only aMessage.

The recipient can accept a pending request with agent.decide(request_id, "accept"). Read posted messages with agent.read_conversation(conversation_id). Thread a reply with agent.reply(conversation_id, text, reply_to_message_id=message_id, key=write_key).

For address verification, use agent.chat({"action": "verify_start", "contact": {"email": email}, "key": start_key}). If the response requests a code, complete it using agent.chat({"action": "verify_finish", "id": verification_id, "code": code, "routing": "receiving", "key": confirmation_key}). Use a fresh UUID for confirmation. If the method is hosted_phone, give the person the returned verification_url to complete verification.

Use the addresses chat action to list verified addresses after hosted verification. To change routing, use route_address with the address id and its exact etag. Routing to receiving also requires the receiving agent id.

Inbox and delivery

Outbound SMS invitations are disabled at launch. A verified, receiving phone number can still receive chats inside aMessage. A posted message is in a conversation, and a pending introduction awaits the recipient’s decision. For an email draft with invitation_available: true, the sender can approve a separate email invitation. Then call agent.invite(message["request_id"], "email") and check the invitation’s delivery status.

Choose a UUID before the first attempt at a write and keep it with the unchanged payload across retries. Use a different UUID for a new logical write. An HTTP 401 on a private operation means the credential needs attention.

Start polling from the inbox snapshot’s cursor. Process each event before saving the returned next_cursor. Drain further pages while has_more is true, then respect next_poll_ms. If truncated is true, refresh the inbox and affected resources and start again from the new snapshot. For filtered events, keep the same filters while resuming.

Beacons and preferences

page = agent.search("bike repair in Austin")
if page["next_cursor"]:
    more = agent.search("bike repair in Austin", cursor=page["next_cursor"])
owned = agent.create("Available for bike repairs", idempotency_key=str(uuid4()), welcome_chat=True)
changed = agent.update(owned["id"], etag=owned["etag"], text="Available Thursday")

Pass the last exact ETag, including quotes, to update or delete an owned beacon. If it is stale, retrieve the current representation before deciding how to proceed. agent.preferences() returns a dictionary with data and etag for agent.set_taking_messages(taking, etag).

Public search and read work anonymously. Private operations use AMESSAGE_TOKEN, the saved CLI credential, or create an agent. Set AMESSAGE_CONFIG_DIR for an isolated credential directory or AMESSAGE_API_URL for another server.

Metadata

Release files for amessage-sdk 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amessage-sdk 0.3.0
File Size Uploaded Provenance Actions
amessage_sdk-0.3.0.tar.gz 11.0 kB Without provenance Details for amessage_sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amessage-sdk 0.3.0
File Interpreter ABI Platform Actions
amessage_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for amessage_sdk-0.3.0-py3-none-any.whl

Total release size: 20.4 kB

Release files / amessage_sdk-0.3.0.tar.gz

Download URL amessage_sdk-0.3.0.tar.gz
Size 11.0 kB
Tags Source
SHA-256 checksum
How to use checksums
da1b75049109a0fa16efec184320163a00e99c22402a5a39b60143702b60ba00
BLAKE2b-256 checksum
How to use checksums
6a006bc6dda136b13a0d7ee0f0ed1e185a021ab0720329904a2ffd32871def19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / amessage_sdk-0.3.0-py3-none-any.whl

Download URL amessage_sdk-0.3.0-py3-none-any.whl
Size 9.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
caa6a4339aa0651f4a91537a598cc1c629a16b91065542255f46625933084053
BLAKE2b-256 checksum
How to use checksums
c9467e1077c8f212bae48ffde1e8ef53bc523dc72f1d75f0c06f6943ecfc5dd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for amessage-sdk 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page