Is it possible to use the Architect GetExternalContactAction to look up a customer record solely by phone number without passing a pre-existing contact ID? I am configuring the JSON mapping in Laravel to pass the caller ID, but the action returns empty when I omit the ID field.
{
"id": null,
"name": "Customer Lookup",
"settings": {
"endpoint": "https://myapi.com/contacts",
"method": "GET",
"query": "phone={callerId}"
}
}
If you check the docs, they mention that the GetExternalContactAction relies heavily on the id field to cache and retrieve the contact object within the conversation context. If you omit it, the action often fails to map the response back to a usable contact entity in Architect, which is why you are seeing empty results. From my experience building webhook ingestion middleware in Rails, I handle this by ensuring the external API returns a unique identifier that we then store in the contact definition.
You should modify your JSON to explicitly set the id in the response mapping or ensure the query parameter is correctly interpolated. However, a more robust pattern I use is to make sure the external API endpoint returns a JSON object where the id field matches what you want to store. Here is how I structure the settings in my flows to ensure the phone number lookup works:
{
"id": "${contact.id}",
"name": "Customer Lookup",
"settings": {
"endpoint": "https://myapi.com/contacts",
"method": "GET",
"query": "phone=${callerId}",
"headers": {
"Authorization": "Bearer ${env:API_KEY}"
}
},
"output": {
"contact": {
"id": "${response.id}",
"name": "${response.name}",
"attributes": {
"phone": "${callerId}"
}
}
}
}
In this setup, I explicitly map the response.id to the contact id. If your API does not return an ID, you might need to generate one or use the phone number itself as the unique key in the attributes block. I also noticed that sometimes the callerId variable needs to be explicitly passed from the previous node if it is not globally available in the flow context. I usually verify this by logging the ${callerId} value in a SetData node right before the external contact action. This helps debug whether the issue is with the API call or the variable resolution in Architect. Since I process these events via Sidekiq jobs, I have seen similar timing issues where the variable scope is lost between nodes, so double-checking the variable path is crucial.
It depends, but generally… GetExternalContactAction is not designed for dynamic lookups by arbitrary attributes like phone numbers. It expects a pre-defined contactId to fetch from the external source, or it fails to populate the context correctly as noted above. For a phone-based lookup, you should use the HTTP Request Action instead. This gives you full control over the query parameters and response mapping without the rigid ID constraints of the contact action.
{
"id": "lookup-contact",
"name": "Lookup Contact by Phone",
"settings": {
"endpoint": "https://myapi.com/contacts?phone={contact.phoneNumber}",
"method": "GET",
"headers": {
"Authorization": "Bearer {{secret.token}}"
}
},
"onSuccess": {
"nextNode": "route-to-queue",
"setContactAttributes": {
"externalCustomerId": "{response.body.id}",
"customerTier": "{response.body.tier}"
}
}
}
When managing this via Terraform CX as Code, ensure the action is defined within the genesyscloud_flow resource. I usually separate the HTTP action from the routing logic to keep the state file clean. The key difference is that you must manually map the JSON response body to contact attributes in the onSuccess block. If your external API returns an array, you need to handle that in the mapping expression, e.g., {response.body[0].id}. This approach avoids the caching issues inherent to the contact action and provides a more robust pattern for API-first integrations in Architect.