> 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/persons.md). # Persons WhatsApp Users who contacted your Inbox ## GET /api/v1/persons/ > Filter Persons by string query - search for Persons containing specified text phrase.\ > \ > The API will search in following places:\ > \ > \* \`waba\_payload.wa\_id\`\ > \ > \* \`waba\_payload.profile.name\` ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Persons","description":"WhatsApp Users who contacted your Inbox"}],"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":{"PaginatedPersonList":{"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/Person"}}}},"Person":{"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."},"waba_payload":{"$ref":"#/components/schemas/WabaPayloadContact"},"initials":{"type":"string","description":"Contact user name initials used for display when avatar image is missing"},"last_message_timestamp":{"type":"number","format":"double","nullable":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) of last message that was sent by this contact. It is the floor of the customer care messaging window: a non-template message can always be delivered for some time after the customer last wrote to your business, and Meta may keep the window open for longer — see `messaging_window_expires_at`. Read more at WhatsApp Business API docs [Messages Cut-off Control](https://developers.facebook.com/docs/whatsapp/api/messages#cut-off-control)."},"messaging_window_expires_at":{"type":"number","format":"double","readOnly":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) after which a non-template message to this contact is rejected with HTTP 453. Derived from what Meta reported for this conversation, the customer's last message, and — for click-to-WhatsApp chats we have not replied to yet — the ad referral. Never assume a fixed duration: read this value."},"messaging_window_origin":{"type":"string","readOnly":true,"nullable":true,"description":"`conversation.origin.type` reported by Meta alongside `messaging_window_expires_at` — what opened the conversation (e.g. `service`, `marketing`, `utility`, `authentication`, or `referral_conversion` for a click-to-WhatsApp ad)."},"resolved":{"type":"boolean","description":"Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages."}},"required":["bsuid","initials","messaging_window_expires_at","messaging_window_origin","phone_number","wa_id","waba_payload"]},"WabaPayloadContact":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/WabaPayloadProfile"},"wa_id":{"type":"string"}},"required":["profile","wa_id"]},"WabaPayloadProfile":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}},"paths":{"/api/v1/persons/":{"get":{"operationId":"listPeople","description":"Filter Persons by string query - search for Persons containing specified text phrase.\n\nThe API will search in following places:\n\n* `waba_payload.wa_id`\n\n* `waba_payload.profile.name`","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"offset","schema":{"type":"integer"}},{"in":"query","name":"search","schema":{"type":"string"}}],"tags":["Persons"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPersonList"}}},"description":""}}}}}} ``` ## GET /api/v1/persons/{wa\_id}/ > ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Persons","description":"WhatsApp Users who contacted your Inbox"}],"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":{"Person":{"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."},"waba_payload":{"$ref":"#/components/schemas/WabaPayloadContact"},"initials":{"type":"string","description":"Contact user name initials used for display when avatar image is missing"},"last_message_timestamp":{"type":"number","format":"double","nullable":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) of last message that was sent by this contact. It is the floor of the customer care messaging window: a non-template message can always be delivered for some time after the customer last wrote to your business, and Meta may keep the window open for longer — see `messaging_window_expires_at`. Read more at WhatsApp Business API docs [Messages Cut-off Control](https://developers.facebook.com/docs/whatsapp/api/messages#cut-off-control)."},"messaging_window_expires_at":{"type":"number","format":"double","readOnly":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) after which a non-template message to this contact is rejected with HTTP 453. Derived from what Meta reported for this conversation, the customer's last message, and — for click-to-WhatsApp chats we have not replied to yet — the ad referral. Never assume a fixed duration: read this value."},"messaging_window_origin":{"type":"string","readOnly":true,"nullable":true,"description":"`conversation.origin.type` reported by Meta alongside `messaging_window_expires_at` — what opened the conversation (e.g. `service`, `marketing`, `utility`, `authentication`, or `referral_conversion` for a click-to-WhatsApp ad)."},"resolved":{"type":"boolean","description":"Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages."}},"required":["bsuid","initials","messaging_window_expires_at","messaging_window_origin","phone_number","wa_id","waba_payload"]},"WabaPayloadContact":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/WabaPayloadProfile"},"wa_id":{"type":"string"}},"required":["profile","wa_id"]},"WabaPayloadProfile":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}},"paths":{"/api/v1/persons/{wa_id}/":{"get":{"operationId":"retrievePerson","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Persons"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}},"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/persons.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.