Twilio Complete Message Conversation Based ContactId

Mobile_API »Get Message Conversation

Base URL

https://apimobile.callproof.com

Endpoint

/api/message-conversation/{contact_id}/{contact_phone_id}

Purpose

Retrieves a paginated SMS/MMS conversation for a contact phone number, grouped by date. Also marks the conversation messages as seen when loaded, and returns contact header details (person name, company, image, and location).

HTTP Method

GET

Headers

Header	Required	Description
Authorization	Yes	Bearer access token

Security

• Yes – Requires Bearer Token authentication.

Parameters

Path Parameters

Parameter	Type	Required	Description
contact_id	integer	Yes	Unique identifier of the contact
contact_phone_id	integer	Yes	Unique identifier of the contact phone number for the conversation

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination (default: 1). Page size is 20

Request Body

None.

Successful Response (200)

Returns conversation messages grouped by date, plus pagination and contact header fields.

Field	Type	Description
clientStatusCode	integer	Status indicator for the client (for example, 200)
user_id	integer	Identifier of the authenticated user
company_id	integer	Identifier of the authenticated user’s company
data	array	Conversation groups by date (see below)
firstItemOnPage	integer	Index of the first item on the current page
lastItemOnPage	integer	Index of the last item on the current page
hasNextPage	boolean	Whether a next page is available
hasPreviousPage	boolean	Whether a previous page is available
isFirstPage	boolean	Whether the current page is the first page
isLastPage	boolean	Whether the current page is the last page
next_page_url	string/null	URL of the next page, when available
prev_page_url	string/null	URL of the previous page, when available
first_page_url	string	URL of the first page
last_page_url	string	URL of the last page
pageCount	integer	Total number of pages
pageNumber	integer	Current page number
pageSize	integer	Number of items per page (20)
totalItemCount	integer	Total number of messages
contact_person_name	string	Person name linked to the phone, when available
contact_company_name	string	Company name for the contact
image	string	Contact/person image path or URL, when available
latitude	string/number	Contact latitude, when available
longitude	string/number	Contact longitude, when available
uri	string	Requested resource URI

data[]

Field	Type	Description
date	string	Display date/time label for the group
message_data	array	Messages in that date group

data[].message_data[]

Field	Type	Description
id	integer	Unique identifier of the message
company_id	integer	Company identifier
contact_id	integer	Contact identifier
contact_phone_id	integer	Contact phone identifier
user_id	integer	User associated with the message
twilio_phone_id	integer	Twilio phone number identifier
sms_type_id	integer	SMS type identifier (for example, inbound/outbound)
start	string	Message date in the user’s timezone (Y-m-d)
time	string	Message time in the user’s timezone (for example, g:i a)
message	string	Message text body
sent	boolean	Whether the message was sent successfully
seen	boolean	Whether the message has been seen
failed	boolean	Whether the message failed
carrier_name	string	Carrier name, when available
caller_name	string	Caller name, when available
is_new_contact_sms	boolean	Whether this is a new-contact SMS
wait_time	string/number	Wait time value, when available
error_detail	string	Error details when the message failed
mms_url	array	List of MMS media URLs attached to the message

Error Responses

Status Code	Meaning
400	Bad Request – conversation could not be retrieved
401	Unauthorized – missing, invalid, or expired Bearer token

• 400 – Contact not found ("Contact not found"), contact phone not found ("Contact Phone Id not found"), or another retrieval error (for example, "Error while retrieving the twilio conversation details").
• 401 – Authentication failed or the access token is missing/expired.