As suggested in review: it's confusing for most people, and signal-cli returns an error if it doesn't apply. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.3 KiB
Sample REST API calls
- Register a number (with SMS verification)
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/<number>'
numberis your cell phone number which you want to link to the docker container.
e.g:
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291'
- Register a number (with voice verification)
curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/<number>'
e.g:
curl -X POST -H "Content-Type: application/json" --data '{"use_voice": true}' 'http://127.0.0.1:8080/v1/register/+431212131491291'
-
Register a number (with captcha)
When you try to register a number, if you receive a response like
{"error":"Captcha required for verification (null)\n"}then Signal is requiring a captcha. To register the number you must do the following:- Go to https://signalcaptchas.org/registration/generate.html
- Open the developer console
- Find the line that looks like this:
Prevented navigation to “signalcaptcha://{captcha value}” due to an unknown protocol.Copy the captcha value (e.g.signal-hcaptcha-short.xxxxx.registration.yyyyyy). Note: do not includesignalcaptcha://. - Use it to make the registration call like this:
curl -X POST -H "Content-Type: application/json" -d '{"captcha":"captcha value"}' 'http://127.0.0.1:8080/v1/register/<number>'or via voice
curl -X POST -H "Content-Type: application/json" -d '{"captcha":"captcha value","use_voice": true}' 'http://127.0.0.1:8080/v1/register/<number> -
Verify the number using the code received via SMS/voice
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/<number>/verify/<verification code>'e.g:
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/register/+431212131491291/verify/123-456' -
Send a message to multiple recipients
curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v2/send'e.g:
curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "+431212131491291", "recipients": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v2/send' -
Send a message (+ base64 encoded attachment) to multiple recipients
curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "base64_attachments": ["<base64 encoded attachment>"], "number": "<number>", "recipients": ["<recipient1>", "<recipient2>"]}' 'http://127.0.0.1:8080/v2/send' -
Send a message with a base64 encoded attachment
e.g:
TMPFILE="$(base64 image_9.jpg)"curl -X POST -H "Content-Type: application/json" -d '{"message": "Test image", "base64_attachments": ["'"${TMPFILE}"'"], "number": "+431212131491291", "recipients": ["+4354546464654"]}' 'http://127.0.0.1:8080/v2/send'For sending larger files such as a 4MB mp4 video file:
TMPFILE="$(base64 video.mp4)"echo '{"message": "Test video", "base64_attachments": ["'"$TMPFILE"'"], "number": "+431212131491291", "recipients": ["+4354546464654"]}' | curl -X POST -H "Content-Type: application/json" -d @- 'http://127.0.0.1:8080/v2/send' -
Send a message to a group
The group id can be obtained via the "List groups" REST call.
curl -X POST -H "Content-Type: application/json" -d '{"message": "<message>", "number": "<number>", "recipients": ["<group id>"]}' 'http://127.0.0.1:8080/v2/send'e.g:
curl -X POST -H "Content-Type: application/json" -d '{"message": "Hello World!", "number": "+431212131491291", "recipients": ["group.ckRzaEd4VmRzNnJaASAEsasa", "+4912812812121"]}' 'http://127.0.0.1:8080/v2/send' -
Send a message including a link preview
curl -X POST -H "Content-Type: application/json" -d '{"message": "Hey, check out https://www.homeassistant.io", "number": "<number>", "recipients": [<recipient1>], "link_preview": {"url": "https://www.homeassistant.io", "title": "Home Assistant", "base64_thumbnail": "'"$( base64 -w 0 <imagepath>)"'"}}' 'http://127.0.0.1:8080/v2/send'e.g:
curl -X POST -H "Content-Type: application/json" -d '{"message": "Hey, check out https://www.homeassistant.io", "number": "+431212131491291", "recipients": [+4354546464654], "link_preview": {"url": "https://www.homeassistant.io", "title": "Home Assistant", "base64_thumbnail": "'"$( base64 -w 0 /tmp/logo.png)"'"}}' 'http://127.0.0.1:8080/v2/send' -
Receive messages
Fetch all new messages in the inbox of the specified number.
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/<number>'numberis the registered phone number for which you want to retrieve incoming messages.This is a WebSocket connection that remains subscribed to live events. Through this connection, you can observe real-time actions, such as when someone is typing or sending a message.
e.g:
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/receive/+431212131491291'or with wscat:
wscat -c ws://127.0.0.1:8080/v1/receive/+431212131491291 --show-ping-pong --slash -
Create a new group
Create a new group with the specified name and members.
curl -X POST -H "Content-Type: application/json" -d '{"name": "<group name>", "members": ["<member1>", "<member2>"]}' 'http://127.0.0.1:8080/v1/groups/<number>'e.g:
curl -X POST -H "Content-Type: application/json" -d '{"name": "my group", "members": ["+4354546464654", "+4912812812121"]}' 'http://127.0.0.1:8080/v1/groups/+431212131491291' -
List groups
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>'e.g:
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/+431212131491291' -
Delete a group
Delete the group with the given group id. The group id can be obtained via the "List groups" REST call.
curl -X DELETE -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>/<group id>'e.g:
curl -X DELETE -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/+431212131491291/ckRzaEd4VmRzNnJaASAEsasa' -
Terminate (end) a group for everyone
Permanently end the group with the given group id for all members. Afterwards nobody, not even an admin, can send messages or start calls in the group, but members keep the message history. This can't be undone. The account must be an admin of the group.
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/<number>/<group id>/terminate'e.g:
curl -X POST -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/groups/+431212131491291/group.ckRzaEd4VmRzNnJaASAEsasa/terminate' -
Link a device
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/qrcodelink?device_name=<device name>'e.g:
curl -X GET -H "Content-Type: application/json" 'http://127.0.0.1:8080/v1/qrcodelink?device_name=HomeAssistant'This provides a QR-Code image. In case of an error a JSON object will be returned.
Due to security reason of Signal, the provided QR-Code will change with each request.
The following REST API endpoints are deprecated and no longer maintained!
/v1/send