Device actions — profile, presence and chat typing

`PATCH /devices/{id}/profile`

Sets the WhatsApp display name (JSON) or profile photo (multipart) of a rented number.


Scope	`device`
Body	`application/json` with `pushName`, or `multipart/form-data` with `avatar`

JSON — the display name

Field	Type	Required	Validation
`pushName`	string	yes	Trimmed length 1–64

curl -X PATCH https://app.maukirim.com/api/v1/devices/gwd_…/profile \
  -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"pushName": "Studio Support"}'

{ "ok": true, "pushName": "Studio Support" }

multipart — the profile photo

Part	Type	Required	Validation
`avatar`	File	yes	`image/jpeg` or `image/png`, greater than 0 and at most 5 MiB; the bytes are checked against the declared type

curl -X PATCH https://app.maukirim.com/api/v1/devices/gwd_…/profile \
  -H "Authorization: Bearer mk_live_…" \
  -F "avatar=@logo.png;type=image/png"

{ "ok": true, "hasAvatar": true }

Changing the photo replaces the previous one. WhatsApp’s API has no “remove photo” operation, so a photo once set can only be replaced.

Errors for both shapes

HTTP	Code	Condition
400	`invalid_input`	`pushName` not a string, empty or over 64 characters; missing `avatar` part; type not JPEG/PNG; empty file; over 5 MiB; bytes that do not match the declared type
404	`rental_not_found`	No usable rental for this device and account
404	`device_not_found`	The device is no longer in the gateway’s inventory
409	`device_not_connected`	The WhatsApp session is not connected/logged in
409	`gateway_disabled`	The device’s gateway is switched off or has never been reached
409	`rental_device_not_ready`	The device has not been seen recently enough to take a write
410	`media_unavailable`	No private media bucket is configured, so an avatar cannot be stored
401/403	auth codes	Needs scope `device`
500	`server_error`	Unexpected, including a gateway call that failed (unreachable, timed out, or refused)

`POST /devices/{id}/presence`

Sets the number’s online presence.


Scope	`device`
Body	`application/json`

Field	Type	Required	Validation
`type`	string	yes	`available` or `unavailable`

curl -X POST https://app.maukirim.com/api/v1/devices/gwd_…/presence \
  -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"type": "unavailable"}'

{ "ok": true, "type": "unavailable" }

This is WhatsApp’s “online” indicator. Nothing is stored server-side, so it is not a way to read presence — it is a way to set it.

To receive per-chat typing events, subscribe to the chat_presence webhook event.

Errors

400 invalid_input (missing or unknown type), plus the same 404 rental_not_found, 404 device_not_found, 409 device_not_connected, 409 gateway_disabled and 409 rental_device_not_ready as the profile route, the auth codes for scope device, and 500 server_error when the gateway call itself fails.

`POST /devices/{id}/chat-presence`

Start or stop the typing indicator in one recipient chat on a number you rent.


Scope	`device`
Body	`application/json`

Field	Type	Required	Validation
`phone`	string	yes	Recipient in E.164 format, such as `+6281234567890`; spaces, dots, dashes and parentheses are stripped before validation
`action`	string	yes	`start` or `stop`

curl -X POST https://app.maukirim.com/api/v1/devices/gwd_…/chat-presence \
  -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"phone":"+6281234567890","action":"start"}'

{ "ok": true, "action": "start" }

Use stop with the same phone when you want to clear typing. The response acknowledges the gateway action; it is not a message or delivery receipt. This call takes no Idempotency-Key and does not bill a message. The rental must be active or in grace, the gateway healthy, and the device connected and recently seen.

HTTP	Code	Condition
400	`invalid_input`	`phone` is not an E.164 string, or `action` is neither `start` nor `stop`
403	`api_key_scope_denied`	The key does not hold `device`
404	`rental_not_found`	No usable rental for this device and account — including a device rented by another account
404	`device_not_found`	The device left the gateway’s inventory
409	`device_not_connected`	The WhatsApp session is not connected or not logged in
409	`gateway_disabled`	The device’s gateway is switched off or has never been reached
409	`rental_device_not_ready`	The device has not been seen recently enough to act on
500	`server_error`	The gateway call failed (unreachable, timed out, or refused)