# Contact
## Assign a contact to a user
> \\- Roles Allowed: ADMIN \
\- Impersonated User Allowed: False \
\- Partner Allowed: True \
\- API will assign a contact to a user or a group from which the user can be selected. Only one of them is required, if both are provided, user\_id will be used\
\- assign\_on\_handover is a boolean flag to indicate if the user should be assigned to the chatroom after the lead has responded\
\
```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AssignChatroomReqDto":{"type":"object","properties":{"user_id":{"type":"string"},"group_id":{"type":"string"},"remote_waba_id":{"type":"string"},"remote_phone_id":{"type":"string"},"assign_on_handover":{"type":"boolean"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v3/orgs/{orgId}/contacts/{contactId}/assign":{"post":{"tags":["chatroom-controller"],"summary":"Assign a contact to a user","description":"- Roles Allowed: ADMIN
- Impersonated User Allowed: False
- Partner Allowed: True
- API will assign a contact to a user or a group from which the user can be selected. Only one of them is required, if both are provided, user_id will be used
- assign_on_handover is a boolean flag to indicate if the user should be assigned to the chatroom after the lead has responded
","operationId":"assignChatroom","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignChatroomReqDto"}}},"required":true},"responses":{"202":{"description":"User will be assigned to the room"},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"Cannot make this request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"User / Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Required fields are missing or invalid values are provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"429":{"description":"Rate limit exceeded. Allows 1 request per 10 seconds per contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Internal Exception","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```
## Create a contact
> \\- Roles Allowed: ADMIN\
\- Impersonated User Allowed: False \
\- Partner Allowed: True \
\- Error Codes : Error Message \
\ 4030001 : FORBIDDEN \
\ 4090001 : UQ\_CONSTRAINT\_FAILED \
\
```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ContactReqDto":{"required":["crm_id","opt_in_date","phone_number"],"type":"object","properties":{"crm_id":{"maxLength":128,"minLength":0,"type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"},"opt_in_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"first_name":{"maxLength":128,"minLength":0,"pattern":"^(?!.*\\*).*$","type":"string"},"last_name":{"maxLength":128,"minLength":0,"pattern":"^(?!.*\\*).*$","type":"string"},"governance_level_id":{"maxLength":128,"minLength":0,"type":"string"},"is_inbound":{"type":"boolean"},"source":{"type":"string","enum":["BTRIX","CAMPAIGN"]}}},"PhoneNumber":{"type":"object","properties":{"extension":{"type":"string"},"countryCode":{"type":"integer","format":"int32"},"nationalNumber":{"type":"integer","format":"int64"},"italianLeadingZero":{"type":"boolean"},"rawInput":{"type":"string"},"preferredDomesticCarrierCode":{"type":"string"},"countryCodeSource":{"type":"string","enum":["FROM_NUMBER_WITH_PLUS_SIGN","FROM_NUMBER_WITH_IDD","FROM_NUMBER_WITHOUT_PLUS_SIGN","FROM_DEFAULT_COUNTRY","UNSPECIFIED"]},"numberOfLeadingZeros":{"type":"integer","format":"int32"}},"description":"e164 format"},"ContactRespDto":{"type":"object","properties":{"id":{"type":"string"},"crm_id":{"type":"string"},"opt_in_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"create_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"first_name":{"type":"string"},"last_name":{"type":"string"},"governance_level":{"$ref":"#/components/schemas/GovernanceLevelDto"},"is_expired":{"type":"boolean"}}},"GovernanceLevelDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v2/org/{orgId}/contact":{"post":{"tags":["contact-controller"],"summary":"Create a contact","description":"- Roles Allowed: ADMIN
- Impersonated User Allowed: False
- Partner Allowed: True
- Error Codes : Error Message
4030001 : FORBIDDEN
4090001 : UQ_CONSTRAINT_FAILED
","operationId":"registerContactV2","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactReqDto"}}},"required":true},"responses":{"200":{"description":"Successfully registered contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRespDto"}}}},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"User or Partner is not allowed to create a contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"409":{"description":"Conflicting entry in DB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Invalid format or bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Internal Exception","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```
## Update a contact
> \\- Roles Allowed: ADMIN\
\- Impersonated User Allowed: FALSE \
\- Partner Allowed: TRUE\
\- Update contact crmID, first name, last name and chatroom name will be automatically updated \
\
```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UpdateContactReqDto":{"required":["crm_id"],"type":"object","properties":{"crm_id":{"maxLength":128,"minLength":0,"type":"string"},"first_name":{"maxLength":128,"minLength":0,"pattern":"^(?!.*\\*).*$","type":"string"},"last_name":{"maxLength":128,"minLength":0,"pattern":"^(?!.*\\*).*$","type":"string"}}},"ContactRespDto":{"type":"object","properties":{"id":{"type":"string"},"crm_id":{"type":"string"},"opt_in_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"create_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"first_name":{"type":"string"},"last_name":{"type":"string"},"governance_level":{"$ref":"#/components/schemas/GovernanceLevelDto"},"is_expired":{"type":"boolean"}}},"GovernanceLevelDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v1/orgs/{orgId}/contact/{contactId}":{"put":{"tags":["contact-controller"],"summary":"Update a contact","description":"- Roles Allowed: ADMIN
- Impersonated User Allowed: FALSE
- Partner Allowed: TRUE
- Update contact crmID, first name, last name and chatroom name will be automatically updated
","operationId":"updateContact","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactReqDto"}}},"required":true},"responses":{"200":{"description":"Successfully updated contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRespDto"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"User does not belong to org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Required fields are missing or invalid values are provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Failed to update contact due to internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```
## Update disposition & stage for a contact
> \\- Roles Allowed: ADMIN\
\- Impersonated User Allowed: True \
\- Partner Allowed: TRUE\
\
```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UpdateContactDispositionReqV2Dto":{"required":["stage"],"type":"object","properties":{"additionalFields":{"type":"object","additionalProperties":{"type":"object"}},"stage":{"type":"string"},"disposition":{"type":"string"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v2/orgs/{orgId}/contact/{contactId}/disposition":{"put":{"tags":["contact-controller"],"summary":"Update disposition & stage for a contact","description":"- Roles Allowed: ADMIN
- Impersonated User Allowed: True
- Partner Allowed: TRUE
","operationId":"updateContactDispositionV2","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactDispositionReqV2Dto"}}},"required":true},"responses":{"200":{"description":"Successfully updated contact disposition","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"User does not belong to org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Required fields are missing or invalid values are provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Failed to add contact disposition due to internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```
## Get Contact by Phone Number
> \\- Roles Allowed: MEMBER\
\- Impersonated User Allowed: True \
\- Partner Allowed: True \
\- PhoneNumber should be in E164 format \
\- The result will contain all contacts for a given pn.\
\
```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GetContactRespDto":{"type":"object","properties":{"id":{"type":"string"},"crm_id":{"type":"string"},"opt_in_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"create_date":{"type":"string","description":"epoch in seconds","format":"date-time"},"first_name":{"type":"string"},"last_name":{"type":"string"},"is_expired":{"type":"boolean"},"expiry_ts":{"type":"string","format":"date-time"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v2/org/{orgId}/contact/pn/{phoneNumber}":{"get":{"tags":["contact-controller"],"summary":"Get Contact by Phone Number","description":"- Roles Allowed: MEMBER
- Impersonated User Allowed: True
- Partner Allowed: True
- PhoneNumber should be in E164 format
- The result will contain all contacts for a given pn.
","operationId":"getContactByPhoneV2","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"phoneNumber","in":"path","description":"e164 format","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully responding with list of all contacts for a pn","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GetContactRespDto"}}}}},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"Forbidden - You don't have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Phone Number not in the correct format or required fields are missing or invalid values are provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.saleschat.pro/api-documentation/contact.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.