View source for Twilio Complete Message Conversation Based ContactId

== 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 ===
{| class="wikitable"
! Header !! Required !! Description
|-
| Authorization || Yes || Bearer access token
|}

=== Security ===
* '''Yes''' – Requires Bearer Token authentication.

=== Parameters ===

==== Path Parameters ====
{| class="wikitable"
! 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 ====
{| class="wikitable"
! 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.

{| class="wikitable"
! 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[] ====
{| class="wikitable"
! Field !! Type !! Description
|-
| date || string || Display date/time label for the group
|-
| message_data || array || Messages in that date group
|}

==== data[].message_data[] ====
{| class="wikitable"
! 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 (<code>Y-m-d</code>)
|-
| time || string || Message time in the user’s timezone (for example, <code>g:i a</code>)
|-
| 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 ===
{| class="wikitable"
! 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.