> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/assignment.md). # Assignment You can assign Chats to Users or Groups. ## GET /api/v1/chat\_assignment/{wa\_id}/ > Get who a Chat is assigned to: a User, a Group, or nobody. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Assignment","description":"You can assign Chats to Users or Groups."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ChatAssignment":{"type":"object","properties":{"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.","pattern":"^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$","maxLength":200},"bsuid":{"type":"string","readOnly":true,"nullable":true,"title":"Business-Scoped User ID","description":"Business-Scoped User ID for this contact. Populated from the webhook's `user_id` field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier."},"phone_number":{"type":"string","readOnly":true,"nullable":true,"description":"Phone number when known. Equals `wa_id` for phone-primary contacts. For BSUID-primary contacts (where `wa_id` is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book."},"assigned_to_user":{"type":"integer","nullable":true},"assigned_group":{"type":"integer","nullable":true}},"required":["bsuid","phone_number","wa_id"]}}},"paths":{"/api/v1/chat_assignment/{wa_id}/":{"get":{"operationId":"retrieveChatAssignment","description":"Get who a Chat is assigned to: a User, a Group, or nobody.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Assignment"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}}},"description":""}}}}}} ``` ## PUT /api/v1/chat\_assignment/{wa\_id}/ > Assign a Chat to yourself or any User or Group\ > \ > You can remove Chat assignment by passing \`null\` value. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Assignment","description":"You can assign Chats to Users or Groups."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ChatAssignment":{"type":"object","properties":{"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.","pattern":"^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$","maxLength":200},"bsuid":{"type":"string","readOnly":true,"nullable":true,"title":"Business-Scoped User ID","description":"Business-Scoped User ID for this contact. Populated from the webhook's `user_id` field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier."},"phone_number":{"type":"string","readOnly":true,"nullable":true,"description":"Phone number when known. Equals `wa_id` for phone-primary contacts. For BSUID-primary contacts (where `wa_id` is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book."},"assigned_to_user":{"type":"integer","nullable":true},"assigned_group":{"type":"integer","nullable":true}},"required":["bsuid","phone_number","wa_id"]}}},"paths":{"/api/v1/chat_assignment/{wa_id}/":{"put":{"operationId":"updateChatAssignment","description":"Assign a Chat to yourself or any User or Group\n\nYou can remove Chat assignment by passing `null` value.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Assignment"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}}},"description":""}}}}}} ``` ## PATCH /api/v1/chat\_assignment/{wa\_id}/ > Assign a Chat to yourself or any User or Group\ > \ > You can remove Chat assignment by passing \`null\` value. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Assignment","description":"You can assign Chats to Users or Groups."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"PatchedChatAssignment":{"type":"object","properties":{"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.","pattern":"^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$","maxLength":200},"bsuid":{"type":"string","readOnly":true,"nullable":true,"title":"Business-Scoped User ID","description":"Business-Scoped User ID for this contact. Populated from the webhook's `user_id` field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier."},"phone_number":{"type":"string","readOnly":true,"nullable":true,"description":"Phone number when known. Equals `wa_id` for phone-primary contacts. For BSUID-primary contacts (where `wa_id` is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book."},"assigned_to_user":{"type":"integer","nullable":true},"assigned_group":{"type":"integer","nullable":true}}},"ChatAssignment":{"type":"object","properties":{"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.","pattern":"^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$","maxLength":200},"bsuid":{"type":"string","readOnly":true,"nullable":true,"title":"Business-Scoped User ID","description":"Business-Scoped User ID for this contact. Populated from the webhook's `user_id` field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier."},"phone_number":{"type":"string","readOnly":true,"nullable":true,"description":"Phone number when known. Equals `wa_id` for phone-primary contacts. For BSUID-primary contacts (where `wa_id` is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book."},"assigned_to_user":{"type":"integer","nullable":true},"assigned_group":{"type":"integer","nullable":true}},"required":["bsuid","phone_number","wa_id"]}}},"paths":{"/api/v1/chat_assignment/{wa_id}/":{"patch":{"operationId":"partialUpdateChatAssignment","description":"Assign a Chat to yourself or any User or Group\n\nYou can remove Chat assignment by passing `null` value.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Assignment"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedChatAssignment"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedChatAssignment"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedChatAssignment"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAssignment"}}},"description":""}}}}}} ``` ## POST /api/v1/chat\_assignment/{wa\_id}/auto-assignment/ > Assign a Chat to an automatically selected User ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Assignment","description":"You can assign Chats to Users or Groups."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ChatAutoAssignment":{"type":"object","properties":{"wa_id":{"type":"string","readOnly":true,"title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number."},"assigned_to_user":{"type":"integer","readOnly":true,"nullable":true,"description":"ID of the User this Chat is assigned to"}},"required":["assigned_to_user","wa_id"]}}},"paths":{"/api/v1/chat_assignment/{wa_id}/auto-assignment/":{"post":{"operationId":"autoAssignment","description":"Assign a Chat to an automatically selected User","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Assignment"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAutoAssignment"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ChatAutoAssignment"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ChatAutoAssignment"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAutoAssignment"}}},"description":""}}}}}} ``` ## GET /api/v1/chat\_assignment\_events/ > List all Chat assignment events for selected Chat ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Assignment","description":"You can assign Chats to Users or Groups."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"PaginatedChatAssignmentEventList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ChatAssignmentEvent"}}}},"ChatAssignmentEvent":{"type":"object","properties":{"timestamp":{"type":"number","format":"double"},"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID of the Chat for which the assignment was changed","maxLength":1000},"assigned_to_user_set":{"$ref":"#/components/schemas/User"},"assigned_to_user_was_cleared":{"type":"boolean"},"assigned_group_set":{"$ref":"#/components/schemas/Group"},"assigned_group_was_cleared":{"type":"boolean","title":"Assigned to group was cleared"},"done_by":{"$ref":"#/components/schemas/User"}},"required":["assigned_group_set","assigned_to_user_set","done_by","timestamp"]},"User":{"type":"object","properties":{"url":{"type":"string","format":"uri","readOnly":true},"id":{"type":"integer","readOnly":true},"username":{"type":"string","description":"Username that is used in combination with password during login.\n\nOnly alphanumeric characters are allowed (A-Z, a-z, 0-9)."},"first_name":{"type":"string","maxLength":150},"last_name":{"type":"string","maxLength":150},"email":{"type":"string","format":"email","description":"E-mail address of this new user.\n\n"},"profile":{"allOf":[{"$ref":"#/components/schemas/UserProfile"}],"description":"Optional field used to create app users and additional admin users"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupMember"},"readOnly":true,"description":"List of group objects the user belongs to (read-only)"},"group_ids":{"type":"array","items":{"type":"integer","writeOnly":true},"writeOnly":true,"description":"List of group IDs to assign to the user (write-only)"},"permissions":{"$ref":"#/components/schemas/Permissions"},"assigned_wa_ids":{"type":"array","items":{"type":"string"},"readOnly":true}},"required":["assigned_wa_ids","email","groups","id","permissions","url","username"]},"UserProfile":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/RoleEnum"}],"description":"

Possible values:
* user (User) - can do everything that isn't marked as admin only in API documentation
* admin (Admin) - can use all available API endpoints and has Inbox admin panel access
* app (App integration) - can do everything regular users have access too, but has no access to inbox web frontend

\n\n* `user` - Regular user\n* `admin` - Admin\n* `app` - App integration"},"is_available":{"type":"boolean","description":"Manual status set by the user to indicate availability for communication."}}},"RoleEnum":{"enum":["user","admin","app"],"type":"string","description":"* `user` - Regular user\n* `admin` - Admin\n* `app` - App integration"},"GroupMember":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"Permissions":{"type":"object","properties":{"can_use_tags":{"type":"boolean","description":"Uncheck this to disable tagging for related Users completely."},"can_read_chats":{"allOf":[{"$ref":"#/components/schemas/CanReadChatsEnum"}],"description":"

Possible values:
all - User can read from All Chats
\ngroup - User can read from Only Chats assigned to User's Groups
\nuser - User can read from Only Chats assigned to User directly
\nnone - User can read from No Chats

\n\n* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats"},"can_write_to_chats":{"allOf":[{"$ref":"#/components/schemas/CanWriteToChatsEnum"}],"description":"

Possible values:
all - User can write to All Chats
\ngroup - User can write to Only Chats assigned to User's Groups
\nuser - User can write to Only Chats assigned to User directly
\nnone - User can write to No Chats

\n\n* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats"}}},"CanReadChatsEnum":{"enum":["all","group","user","none"],"type":"string","description":"* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats"},"CanWriteToChatsEnum":{"enum":["all","group","user","none"],"type":"string","description":"* `all` - All Chats\n* `group` - Only Chats assigned to User's Groups\n* `user` - Only Chats assigned to User directly\n* `none` - No Chats"},"Group":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"name":{"type":"string","maxLength":1000}},"required":["id","name"]}}},"paths":{"/api/v1/chat_assignment_events/":{"get":{"operationId":"listChatAssignmentEvents","description":"List all Chat assignment events for selected Chat","parameters":[{"in":"query","name":"before_time","schema":{"type":"integer"},"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **older** than specified `before_time`.\n\n\nThis should be used when implementing scroll of the event view from newest to oldest."},{"name":"limit","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"The initial index from which to return the results.","schema":{"type":"integer"}},{"in":"query","name":"since_time","schema":{"type":"integer"},"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time).\n Returns only events that are **at the same timestamp or newer** than specified `since_time`.\n Note that, as opposed to `before_time` param, this param returns messages where timestamp is equal\n to the given value.\n\n\nThis should be used when implementing scroll of the event view from oldest to newest."},{"in":"query","name":"wa_id","schema":{"type":"string"},"description":"WhatsApp ID of related Chat"}],"tags":["Assignment"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedChatAssignmentEventList"}}},"description":""}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/assignment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.